Commits

Ronald Oussoren  committed 1713eaf

Rename lib to api to match website

  • Participants
  • Parent commits 767b68e

Comments (0)

Files changed (19)

File pyobjc-core/Doc/api/index.rst

+Python API
+==========
+
+Contents:
+
+.. toctree::
+
+   module-objc
+   module-PyObjCTools

File pyobjc-core/Doc/api/module-PyObjCTools.AppHelper.rst

+=========================================================
+:mod:`PyObjCTools.AppHelper` -- Work with AppKit
+=========================================================
+
+.. module:: PyObjCTools.AppHelper
+   :synopsis: Work with AppKit
+
+This module exports functions that are useful when working with the
+``AppKit`` framework (or more generally, run loops).
+
+.. function:: callAfter(func, *args, **kwargs)
+
+    Call a function on the main thread.  Returns immediately.
+
+.. function:: callLater(delay, func, *args, **kwargs)
+
+    Call a function on the main thread after a delay.  Returns immediately.
+
+.. function:: endSheetMethod(method)
+
+    Convert a method to a form that is suitable to use as the delegate callback
+    for sheet methods.
+    
+    :rtype: selector
+
+.. function:: stopEventLoop()
+
+    Stops the event loop (if started by ``runConsoleEventLoop``) or sends the
+    ``NSApplication`` a ``terminate:`` message.
+
+.. function:: runConsoleEventLoop(argv=None, installInterrupt=False, mode=NSDefaultRunLoopMode)
+
+    Run a ``NSRunLoop`` in a stoppable way (with ``stopEventLoop``).
+
+.. function:: runEventLoop(argv=None, unexpectedErrorAlert=unexpectedErrorAlert, installInterrupt=None, pdb=None, main=NSApplicationMain)
+
+    Run the event loop 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.

File pyobjc-core/Doc/api/module-PyObjCTools.Conversion.rst

+=========================================================
+:mod:`PyObjCTools.Conversion` -- Convert data structures
+=========================================================
+
+.. module:: PyObjCTools.Conversion
+   :synopsis: Convert data structures
+   
+Functions for converting between Cocoa and pure Python data structures.
+
+.. function:: propertyListFromPythonCollection(pyCol, conversionHelper=None)
+
+    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.
+
+.. function:: pythonCollectionFromPropertyList(ocCol, conversionHelper=None)
+
+    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.

File pyobjc-core/Doc/api/module-PyObjCTools.KeyValueCoding.rst

+:mod:`PyObjCTools.KeyValueCoding` -- Key-Value Coding API 
+=========================================================
+
+.. module:: PyObjCTools.KeyValueCoding
+   :platform: MacOS X
+   :synopsis: Key-Value Coding API
+
+.. moduleauthor:: Ronald Oussoren <ronaldoussoren@mac.com>
+
+Support for Key-Value Coding in Python. This provides a simple functional
+interface to Cocoa's Key-Value coding that also works for regular Python
+objects.
+
+Key-Value Coding is Cocoa functionality that is simular to
+the :func:`getattr` and :func:`setattr` functions in Python. The APIs
+in this module are modelled on those functions and work on 
+Cocoa objects as well as basic Python objects.
+
+Key-Value Coding works with keys, basically attribute names, as well as
+key-paths. A key-path is a string that contains a sequence of dot-separated
+keys and is used to chain a number of keys together.
+
+Accessor functions
+------------------
+
+.. function:: getKey(object, key)
+
+   Return the value of the attribute referenced by ``key``. The key
+   is used to build the name of an accessor method or attribute name. 
+
+   The following methods are tried for regular Python objects:
+
+   * Accessor method ``getKey``
+
+   * Accessor method ``get_key``
+
+   * Accessor method or attribute ``key``
+
+   * Accessor meethod or attribute ``isKey``
+
+   * Attribute ``_key``
+ 
+   (In all of these "key" is replaced by the value of ``key``).
+
+   This function calls the regular Key-Value Coding methods for Cocoa objects,
+   including those implemented in Python.
+
+   :param object: An arbitrary object
+   :param key: name of a key
+   :type key: string
+   :result: the value of a key
+   :raise: :exc:`KeyError` when the key does not exist.
+
+
+.. function:: setKey(object, key, value)
+
+   Set the value of the attribute referenced by ``key`` to
+   ``key``. The key is used to build the name of an accessor 
+   method or attribute name. 
+
+   The following methods are tried for regular Python objects:
+
+   * Accessor method ``setKey``
+
+   * Accessor method ``set_key``
+
+   * attribute ``_key``
+
+   * Attribute ``key``
+ 
+   (In all of these "key" is replaced by the value of ``key``).
+
+   This function calls the regular Key-Value Coding methods for Cocoa objects,
+   including those implemented in Python.
+
+   :param object: An arbitrary object
+   :param key: name of a key
+   :param value: The value to set
+   :type key: string
+   :result: the value of a key
+   :raise: :exc:`KeyError` when the key does not exist.
+
+
+.. function:: getKeyPath(object, keypath)
+
+   The ``keypath`` is a string containing a path of keys. The keys
+   are separated by colons, for example :data:`"owner.firstName"`. 
+
+   The key path is used to traverse an object graph to an attribute. This
+   function also supports set and array operators. Those are keys of 
+   the form ``@operator`` are are used as ``pathToArray.@operator.pathToProperty``,
+   for example ``system.disks.@max.capacity``. 
+
+   The table below lists the supported array operators
+
+   =========================== =======================================================
+   Operator
+   =========================== =======================================================
+   ``avg``                     Use the rest of the keypath to fetch the value 
+                               of each item in the container and returns the
+			       average of those values.
+   --------------------------- -------------------------------------------------------
+   ``count``                   Returns the number of items in the container
+   --------------------------- -------------------------------------------------------
+   ``distinctUnionOfArrays``   Use the rest of the keypath to fetch the value of
+                               each item, which must be a sequence. Those sequences
+			       are merged into an array with distict values.
+   --------------------------- -------------------------------------------------------
+   ``distinctUnionOfObjects``  Use the rest of the keypath to fetch the value of
+                               each item and return an array with all distinct
+			       values.
+   --------------------------- -------------------------------------------------------
+   ``max``		       Use the rest of the keypath to fetch the value
+		               of each item in the container and returns the
+			       maximum of those values.
+   --------------------------- -------------------------------------------------------
+   ``min``		       Use the rest of the keypath to fetch the value
+		               of each item in the container and returns the
+			       minimum of those values.
+   --------------------------- -------------------------------------------------------
+   ``sum``		       Use the rest of the keypath to fetch the value
+		               of each item in the container and returns the
+			       sum of those values.
+   --------------------------- -------------------------------------------------------
+   ``unionOfArrays``	       Like ``distinctUnionOfArrays``, but without
+                               removing duplicates.
+   --------------------------- -------------------------------------------------------
+   ``unionOfObjects``	       Like ``distinctUnionOfObjects``, but without
+                               removing duplicates
+   =========================== =======================================================
+
+   This function calls the regular Key-Value Coding method for Cocoa objects.
+
+   :param object: An arbitrary object
+   :param keypath: The keypath, colon seperated keys
+   :type keypath: string
+
+.. function setKeyPath(object, keypath, value)
+
+   The ``keypath`` is a string containing a path of keys. The keys
+   are separated by colons, for example :data:`"owner.firstName"`. 
+
+   The key path is used to traverse an object graph to an attribute and
+   the value is then set simularly to how :func:`setKey` sets the value.
+   
+   :param object: An arbitrary object
+   :param keypath: The keypath, colon seperated keys
+   :type keypath: string
+   :param value: The value to set
+
+
+Key-Value Coding wrapper
+------------------------
+
+.. class:: kvc(value)
+
+   This wrappers ``value`` in an object that uses KeyValue Coding
+   to implement the attribute and item accessors.
+
+   .. method __getattr__(key)
+
+      Returns ``getKey(self, key)``.
+
+   .. method __setattr__(key, value)
+
+      Returns ``setKey(self, key, value)`` if the key
+      does not start with an underscore. 
+      
+      Sets an attribute of the wrapper
+      when the key does start with an undercore.
+
+   .. method __getitem_(self, keypath)
+
+      Returns ``getKeyPath(self, keypath)``
+
+   .. method __setitem_(self, keypath, value)
+
+      Returns ``setKeyPath(self, keypath, value)``

File pyobjc-core/Doc/api/module-PyObjCTools.NibClassBuilder.rst

+================================================
+:mod:`PyObjCTools.NibClassBuilder` -- Magic NIBs
+================================================
+
+.. module:: PyObjCTools.NibClassBuilder
+   :synopsis: Extract definitions from NIBs
+
+.. deprecated:: 2.4
+   Use of this module is deprecated because it cannot be
+   used with modern versions of Xcode (starting at Xcode 4.0),
+   and because recent versions of Xcode can extract class 
+   information from Python sources.
+
+
+Introduction
+------------
+
+The module is used to avoid repeating class inheritance and outlet 
+definitions in both python sources and Interface Builder NIB files. 
+
+The module reads this information from NIB files and provides a magic
+meta class that inserts the right superclass and outlet definitions.
+
+Do not use this module for new developement, it will likely disappear
+in a future version of PyObjC because it can no longer work with modern
+versions of Xcode, and in particular not with XIB files and compiled
+NIB files.
+
+Extracting class definitions from nibs
+--------------------------------------
+
+
+The module maintains a global set of class definitions, extracted from
+nibs. To add the classes from a nib to this set, use the ``extractClasses()``
+function. It can be called in two ways:
+
+.. function:: extractClasses(nibName, bundle=<current-bundle>)
+
+    This finds the nib by name from a bundle. If no bundle
+    if given, the ``objc.currentBundle()`` is searched.
+
+.. function:: extractClasses(path=pathToNib)
+
+    This uses an explicit path to a nib.
+
+``extractClasses()`` can be called multiple times for the same bundle: the
+results are cached so no almost extra overhead is caused.
+
+Using the class definitions
+---------------------------
+
+The module contains a "magic" base (super) class called ``AutoBaseClass``.
+Subclassing ``AutoBaseClass`` will invoke some magic that will look up the
+proper base class in the class definitions extracted from the nib(s).
+If you use multiple inheritance to use Cocoa's "informal protocols",
+you *must* list ``AutoBaseClass`` as the first base class. For example::
+
+    class PyModel(AutoBaseClass, NSTableSource):
+        ...
+
+
+The ``NibInfo`` class
+---------------------
+
+The parsing of nibs and collecting the class definition is done by the
+``NibInfo`` class. You normally don't use it directly, but it's here if you
+have special needs.
+
+The command line tool
+---------------------
+
+When run from the command line, this module invokes a simple command
+line program, which you feed paths to nibs. This will print a Python
+template for all classes defined in the nib(s). For more documentation,
+see the commandline_doc variable, or simply run the program without
+arguments. It also contains a simple test program.

File pyobjc-core/Doc/api/module-PyObjCTools.Signals.rst

+=========================================================
+:mod:`PyObjCTools.Signals` -- Debug signal handling
+=========================================================
+
+.. module:: PyObjCTools.Signals
+   :synopsis: Debug signal handling
+
+This module provides two functions that can be useful while investigating
+random crashes of a PyObjC program. These crashes are often caused by 
+Objective-C style weak references or incorrectly implemented protocols.
+
+.. function:: dumpStackOnFatalSignal()
+
+    This function will install signal handlers that print a stack trace and
+    then re-raise the signal.
+
+.. function:: resetFatalSignals()
+
+    Restores the signal handlers to the state they had before the call to
+    dumpStackOnFatalSignal.
+
+This module is not designed to provide fine grained control over signal 
+handling. Nor is it intended to be terribly robust. It may give useful
+information when your program gets unexpected signals, but it might just
+as easily cause a crash when such a signal gets in.

File pyobjc-core/Doc/api/module-PyObjCTools.TestSupport.rst

+=================================================
+:mod:`PyObjCTools.TestSupport` -- Testing helpers
+=================================================
+
+.. module:: PyObjCTools.TestSupport
+   :synopsis: Testing helpers
+
+This module provides classes and functions that are
+usefull for testing PyObjC itself including the framework
+wrappers.
+
+.. warning::
+
+   This module is primarily used for testing PyObjC 
+   and the API isn't fully stable.
+
+
+.. function:: sdkForPython()
+
+   Returns the SDK version used to compile Python,
+   or :data:`None` when no version can be calculated.
+
+   The SDK version is a tupel with the major
+   and minor versions of Mac OS X (for example ``(10, 8)``).
+
+.. function:: fourcc(value)
+
+   Returns the integer value of a four character code
+   "literal".
+
+   The *value* is a byte string of length 4 and contains
+   the contents of the :c:type:`char` C literal with 
+   the four character code, for example ``b"abcd"``.
+
+.. function:: cast_int(value)
+
+   Return *value* as if it were a 4 byte integer (using
+   the overflow behavior of most CPUs)
+
+.. function:: cast_longlong(value)
+
+   Return *value* as if it were a 8 byte integer (using
+   the overflow behavior of most CPUs)
+
+
+.. function:: cast_uint(value)
+
+   Return *value* as if it were a 4 byte unsigned integer (
+   using the overflow behavior of C)
+
+.. function:: cast_ulonglong(value)
+
+   Return *value* as if it were a 8 byte unsigned integer (using
+   the overflow behavior of C)
+
+.. function:: os_release()
+
+   Returns the major release of Mac OS X on the current machine,
+   for example "10.5" on all systems running a version 
+   of Leopard.
+
+.. function:: is32Bit()
+
+   Returns :data:`True` if the proces is in 32-bit mode.
+
+.. function:: onlyIf(expr, message)
+
+   Decorator for enabling tests only when an expression is true. This is
+   the same as :func:`skipUnless <unittest.skipUnless>` in Python 2.7 or later.
+
+.. function:: onlyPython2
+
+   Decorator for enabling a test only when using Python 2.x.
+
+   This is basicly ``onlyIf(sys.version_info[0] == 2)``.
+
+.. function:: onlyPython3
+
+   Decorator for enabling a test only when using Python 3.x.
+
+   This is basicly ``onlyIf(sys.version_info[0] == 3)``.
+
+.. function:: onlyOn32Bit
+
+   Decorator for enabling a test only when the process is running in 32-bit mode.
+
+.. function:: onlyOn64Bit
+
+   Decorator for enabling a test only when the process is running in 64-bit mode.
+
+.. function:: min_os_level(version)
+
+   Decorator for enabling a test only when running on a recent enough release
+   of Mac OS X.
+
+
+.. function:: max_os_level(version)
+
+   Decorator for enabling a test only when running on a old enough release
+   of Mac OS X.
+
+.. class:: filterWarnings(kind, category)
+
+   A with-statement context that adds a filter to the warnings module
+   while the body of the statement is running.
+
+   This is similar to :class:`warnings.catch_warnings`.
+
+.. class:: TestCase
+
+   A subclass of :class:`unittest.TestCase` with some addition functionality. The
+   most important addition is that each test gets run with a fresh autorelease pool.
+
+   .. method:: assertItemsEqual(seq1, seq2[, message])
+
+      Asserts that sequences *seq1* and *seq2* have the same members (in any order).
+
+   .. method:: assertGreaterThan(value, test[, message])
+
+      Asserts that *value* is greater than *test*.
+
+   .. method:: assertGreaterThanOrEquals(value, test[, message])
+
+      Asserts that *value* is greater than or equal to *test*.
+
+   .. method:: assertLessThan(value, test[, message])
+
+      Asserts that *value* is less than *test*.
+
+   .. method:: assertLessThanOrEquals(value, test[, message])
+
+      Asserts that *value* is less than or equal to *test*.
+
+   .. method:: assertIs(value, test[, message])
+
+      Asserts that *value* is the same object as *test*
+
+   .. method:: assertIsNot(value, test[, message])
+
+      Asserts that *value* is not the same object as *test*
+
+   .. method:: assertIsNone(value[, message])
+
+      Asserts that *value* is the same object as :data:`None`
+
+   .. method:: assertIsNotNone(value[, message])
+
+      Asserts that *value* is the not same object as :data:`None`
+
+   .. method:: assertSstartswith(self, value, check[, message])
+
+      Assert that *value* is a string that starts with *check*.
+
+   .. method:: assertHasAttr(self, value, key[, message])
+
+      Assert that *value* has an attribute named *key*.
+
+   .. method:: assertNotHasAttr(self, value, key[, message])
+
+      Assert that *value* does not have an attribute named *key*.
+
+   .. method:: assertIsInstance(self, value, types[, message])
+
+      Assert that *value* is an instance of *types*.
+
+   .. method:: assertIsNotInstance(self, value, types[, message])
+
+      Assert that *value* is not an instance of *types*.
+
+   .. method:: assertAlmostEquals(val1, val2[, message)
+
+      Assert that *val1* is almost equal to *val2* (that is,
+      the difference between the two values is less that 1e-5)
+
+   .. method:: assertIn(self, value, seq[, message])
+
+      Assert that *value* is a member of *seq*.
+
+   .. method:: assertNotIn(self, value, seq[, message])
+
+      Assert that *value* is not a member of *seq*.
+
+   .. method:: assertIsCFType(tp[, message])
+
+      Asserts that *tp* is a wrapper class for a CoreFoundation type.
+
+   .. method:: assertIsOpaquePointer(tp[, message)
+
+      Asserts that *tp* is a wrapper class for an opaque pointer ("handle")
+
+   .. method:: assertIsNullTerminated(method[, message])
+
+      Asserts that the callable has metadata that indicates that the 
+      callable is variadic function where the argument list is terminated by
+      a null value.
+
+   .. method:: assertResultIsNullTerminated(method[, message])
+
+      Asserts that the callable has metadata that indicates that the result
+      is a null terminated array.
+
+   .. method:: assertArgIsNullTerminated(method, argno[, message])
+
+      Asserts that the callable has metadata that indicates that the argument
+      *argno* is a null terminated array.
+
+
+   .. method:: assertResultIsVariableSize(method[, message])
+
+      Asserts that the callable has metadata that indicates that the result
+      is an array with an unspecified size.
+
+   .. method:: assertArgIsVariableSize(method, argno[, message])
+
+      Asserts that the callable has metadata that indicates that the argument
+      *argno* is an array with an unspecified size.
+
+   .. method:: assertArgSizeInResult(method, argno[, message)
+      Asserts that the callable has metadata that indicates that the argument
+      *argno* is an array where the size of the array is specified in the return value.
+
+   .. method:: assertArgIsPrintf(method, argno[, message])
+
+      Assert that the callable has metadata that specifies that it is a
+      variadic function with a printf-format string in argument *argno*.
+
+   .. method:: assertResultIsCFRetained(method[, message])
+
+      Assert that the callable has metadata that specifies that the
+      retain count of the result is increased by the function (that
+      is, the caller owns the value after the call).
+
+   .. method:: assertResultIsNotCFRetained(method[, message])
+
+      Assert that the callable has metadata that specifies that the
+      retain count of the result is not increased by the function.
+
+   .. method:: assertArgIsCFRetained(method, argno[, message])
+
+      Assert that the callable has metadata that specifies that the
+      retain count of argument *argno* is increased by the function (that
+      is, the caller owns the value after the call).
+
+      .. note:: used to check the behavior of output arguments.
+
+   .. method:: assertArgIsNotCFRetained(method, argno[, message])
+
+      Assert that the callable has metadata that specifies that the
+      retain count of argument *argno* is not increased by the function.
+
+      .. note:: used to check the behavior of output arguments.
+
+   .. method:: assertResultIsRetained(method[, message])
+
+      Assert that the callable has metadata that specifies that the
+      retain count of the result is increased by the function (that
+      is, the caller owns the value after the call).
+
+   .. method:: assertResultIsNotRetained(method[, message])
+
+      Assert that the callable has metadata that specifies that the
+      retain count of the result is not increased by the function.
+
+   .. method:: assertArgIsRetained(method, argno[, message])
+
+      Assert that the callable has metadata that specifies that the
+      retain count of argument *argno* is increased by the function (that
+      is, the caller owns the value after the call).
+
+      .. note:: used to check the behavior of output arguments.
+
+   .. method:: assertArgIsNotRetained(method, argno[, message])
+
+      Assert that the callable has metadata that specifies that the
+      retain count of argument *argno* is not increased by the function.
+
+      .. note:: used to check the behavior of output arguments.
+
+   .. method:: assertResultHasType(method, tp[, message])
+
+      Assert that the result has a specific type encoding.
+
+   .. method:: assertResultIsBOOL(method[, message])
+
+      Assert that the result has type :c:type:`BOOL`.
+
+   .. method:: assertArgHasType(method, argno, tp[, message])
+
+      Assert that the argument *argno* has a specific type encoding.
+
+   .. method:: assertArgIsBOOL(method, argno[, message])
+
+      Assert that the argument *argno* has type :c:type:`BOOL`.
+
+   .. method:: assertArgIsFunction(method, argno, sel_type, retained[, message])
+
+      Assert that argument *argno* is a function with a specific type signature.
+      If *retained* is true the function stores the function reference beyond
+      the end of the function call.
+
+   .. method:: assertResultIsBlock(method, sel_type[, message])
+
+      Assert that the result is a block with a specific type signature.
+
+   .. method:: assertArgIsBlock(method, argno, sel_type[, message])
+
+      Assert that argument *argno* is a block with a specific type signature.
+
+   .. method:: assertArgIsSEL(method, argno, sel_type[, message])
+
+      Assert that argument *argno* is a SEL value for a method with
+      a specific type signature
+
+   .. method:: assertArgIsFixedSize(method, argno, count[, message])
+
+      Assert that argument *argno* is an array of *count* elements.
+
+   .. method:: assertResultSizeInArg(method, count[, message])
+
+      Assert that the result is an array of where the size
+      of the array is specified in argument *count*.
+
+   .. method:: assertArgSizeInArg(method, argno, count[, message])
+
+      Assert that argument *argno* is an array of where the size
+      of the array is specified in argument *count*.
+
+      *count* can also be an tuple of two elements: the first elements
+      specifies the size before the call, the second the size
+      after the call. 
+
+   .. method:: assertArgIsOut(method, argno[, message])
+
+      Assert that argument *argno* is a pass-by-reference output parameter.
+
+   .. method:: assertArgIsIn(method, argno[, message])
+
+      Assert that argument *argno* is a pass-by-reference input parameter.
+
+   .. method:: assertArgIsInOut(method, argno[, message])
+
+      Assert that argument *argno* is a pass-by-reference input and output parameter.
+
+   .. note::
+
+      There are also a number of deprecated aliases for the methods above, those
+      are intentionally not documented.

File pyobjc-core/Doc/api/module-PyObjCTools.rst

+:mod:`PyObjCTools` -- Utilities
+================================
+
+.. module:: PyObjCTools
+   :platform: MacOS X
+   :synopsis: Utilities for PyObjC
+
+.. moduleauthor:: Ronald Oussoren <ronaldoussoren@mac.com>
+
+
+The module :mod:`PyObjCTools` is a namespace package that is filled by
+a number of PyObjC distributions. This package provides useful utilities
+that build upon the core features of PyObjC.
+
+.. toctree::
+
+   module-PyObjCTools.KeyValueCoding.rst
+   module-PyObjCTools.AppHelper.rst
+   module-PyObjCTools.Conversion.rst
+   module-PyObjCTools.NibClassBuilder.rst
+   module-PyObjCTools.Signals.rst
+   module-PyObjCTools.TestSupport.rst

File pyobjc-core/Doc/api/module-objc.rst

+:mod:`objc` -- The PyObjC bridge
+================================
+
+.. module:: objc
+   :platform: MacOS X
+   :synopsis: The PyObjC bridge
+
+.. moduleauthor:: Ronald Oussoren <ronaldoussoren@mac.com>
+
+.. todo::
+
+   This document is too long and needs to be split.
+
+
+Introduction
+------------
+
+The module :mod:`objc` is the core of PyObjC and provides the automatic 
+bridging between Python and Objective-C. It also provides a number of
+utility functions and types that make it easier to integrate Python
+and Objective-C code.
+
+The module :mod:`objc` defines a number of functions whose names start with
+an underscore. Those functions are private and should not be used, they can
+be removed from release without warning.
+
+NOTE: This document is currently mostly an exhaustive list of stuff and 
+needs to be reorganised once I've filled in the technical details. 
+
+Debugging
+.........
+
+.. function:: setVerbose(yesOrNo)
+
+   When the argument is :const:`True` the bridge will log more information.
+
+   This currently results in output on the standard error stream whenever
+   an exception is translated from Python to Objective-C.
+
+
+.. function:: getVerbose()
+
+   Returns the current value of the verbose flag.
+
+
+Tweaking behaviour
+..................
+
+.. function:: setUseKVOForSetattr
+
+   Sets the default value for the *__useKVO__* attribute on
+   classes defined after this call. Returns the previous value.
+
+   When the *__useKVO__* attribute of a class is true instances
+   of the class will generate Key-Value Observation notifications when
+   setting attributes from Python.
+
+.. function:: setHideProtected(yesOrNo)
+
+   When the argument is :const:`True` protected methods of an Objective-C
+   class will not be included in the output of :func:`dir`. Protected methods
+   are those whose selector starts with an underscore.
+
+   This option is on by default.
+
+.. function:: setStrBridgeEnabled(yesOrNo)
+
+   If *yesOrNo* is true instances of :class:`str` are bridged
+   as NSString instances, otherwise bridging issues a :data:`PyObjCStrBridgeWarning`
+   warning and still bridges as an NSString instances.
+
+   By default PyObjC behaves as if ``setStrBridgeEnabled(True)`` was called.
+
+   .. note::
+   
+      This function is not available in Python 3.x
+
+   .. note::
+
+      Setting this option to false is discouraged and is mostly usefull when porting
+      to Python 3.
+
+.. function:: getStrBridgeEnabled
+
+   Returns :data:`True` if the str bridge is enabled and :data:`False` when it is
+   not.
+
+   .. note::
+   
+      This function is not available in Python 3.x
+
+
+Utilities
+..........
+
+.. function:: allocateBuffer(size)
+
+   Returns a writable buffer object of *size* bytes.
+
+.. function:: CFToObject
+
+   Converts an object from the standard library :mod:`CF` module to a
+   PyObjC wrapper for the same CoreFoundation object. Raises an exception
+   when the conversion fails. 
+
+   .. deprecated:: 2.4
+      part of support for the CF module in the python 2 std. library, 
+      will be removed in PyObjC 3.0.
+
+   .. note::
+      this function is not available for Python 3.
+
+
+.. function:: ObjectToCF
+
+   Converts a PyObjC wrapper for a CoreFoundation object to an object from the standard 
+   library :mod:`CF` module for the same CoreFoundation object. Raises an exception
+   when the conversion fails. 
+
+   .. deprecated:: 2.4
+      part of support for the CF module in the python 2 std. library, 
+      will be removed in PyObjC 3.0.
+
+   .. note::
+      this function is not available for Python 3.
+
+
+
+Accessing classes and protocols
+...............................
+
+.. function:: lookUpClass(classname)
+
+   :param classname: the name of an Objective-C class
+   :type classname: string
+   :return: the named Objective-C class
+   :raise: :exc:`objc.nosuchclass_error` when the class does not exist
+
+
+.. function:: getClassList()
+
+   :return: a list of a classes known to the Objective-C runtime
+
+
+.. function:: protocolsForClass(cls)
+
+   Returns a list of Protocol objects that the class claims to 
+   implement directly. The *cls* object must a subclass of NSObject.
+
+.. function:: protocolsForProcess
+
+   Returns a list of all Protocol objects known to the Objective-C
+   runtime.
+
+.. function:: propertiesForClass(objcClass)
+
+   :type objcClass: an Objective-C class or formal protocol
+   :return: a list of properties from the Objective-C runtime
+
+   The return value is a list with information about
+   properties on this class or protocol from the Objective-C runtime. This
+   does not include properties superclasses.
+
+   Every entry in the list is dictionary with the following keys:
+
+   ============= =============================================================
+   Key           Description
+   ============= =============================================================
+   *name*        Name of the property (a string)
+   ------------- -------------------------------------------------------------
+   *raw_attr*    Raw value of the attribute string (a byte string)
+   ------------- -------------------------------------------------------------
+   *typestr*     The type string for this attribute (a byte string)
+   ------------- -------------------------------------------------------------
+   *classname*   When the type string is ``objc._C_ID`` this is the
+                 name of the Objective-C class (a string).
+   ------------- -------------------------------------------------------------
+   *readonly*    True iff the property is read-only (bool)
+   ------------- -------------------------------------------------------------
+   *copy*        True iff the property is copying the value (bool)
+   ------------- -------------------------------------------------------------
+   *retain*      True iff the property is retaining the value (bool)
+   ------------- -------------------------------------------------------------
+   *nonatomic*   True iff the property is not atomic (bool)
+   ------------- -------------------------------------------------------------
+   *dynamic*     True iff the property is dynamic (bool)
+   ------------- -------------------------------------------------------------
+   *weak*        True iff the property is weak (bool)
+   ------------- -------------------------------------------------------------
+   *collectable* True iff the property is collectable (bool)
+   ------------- -------------------------------------------------------------
+   *getter*      Non-standard selector for the getter method (a byte string)
+   ------------- -------------------------------------------------------------
+   *setter*      Non-standard selector for the setter method (a byte string)
+   ============= =============================================================
+
+   All values but *name* and *raw_attr* are optional. The other attributes
+   contain a decoded version of the *raw_attr* value. The boolean attributes
+   should be interpreted as :data:`False` when the aren't present.
+
+   The documentation for the Objective-C runtime contains more information about
+   property definitions.
+
+   This function only returns information about properties as they are defined
+   in the Objective-C runtime, that is using ``@property`` definitions in an
+   Objective-C interface. Not all properties as they are commonly used  in
+   Objective-C are defined using that syntax, especially properties in classes
+   that were introduced before MacOSX 10.5.
+
+   This function always returns an empty list on MacOS X 10.4.
+
+   .. versionadded:: 2.3
+
+.. function:: listInstanceVariables(classOrInstance)
+
+   Returns a list of information about all instance variables for
+   a class or instance. *ClassOrInstance* must be a subclass of NSObject,
+   or an instance of such a class.
+
+   The elements of the list are tuples with two elements: a string with
+   the name of the instance variable and a byte string with the type encoding
+   of the instance variable.
+
+.. function:: getInstanceVariable(object, name)
+
+   Returns the value of the instance variable *name*. 
+
+   .. warning:: 
+
+      Direct access of instance variables should only be used as a debugging
+      tool and could negatively affect the invariants that a class tries to
+      maintain.
+
+.. function:: setInstanceVariable(object, name, value[ ,updateRefCounts])
+
+   Set the value of instance variable *name* to *value*. When the instance variable
+   type encoding is :data:`objc._C_ID` *updateRefCounts* must be specified and tells
+   whether or not the retainCount of the old and new values are updated.
+
+   .. warning:: 
+
+      Direct access of instance variables should only be used as a debugging
+      tool and could negatively affect the invariants that a class tries to
+      maintain.
+
+
+.. function:: protocolNamed(name)
+
+   Returns a Protocol object for the named protocol. Raises :exc:`ProtocolError`
+   when the protocol does not exist.
+
+   This is the equivalent of ``@protocol(name)`` in Objective-C.
+
+.. exception:: ProtocolError
+
+   Raised by :func:`protocolNamed` when looking up a protocol that does not
+   exist.
+
+
+Dynamic modification of classes
+...............................
+
+.. function:: classAddMethods(cls, methods)
+
+   Add a sequence of methods to the given class. 
+   
+   The effect is simular to how categories work in Objective-C. If the class
+   already implements a method that is defined in *methods* the existing
+   implementation is replaced by the new one.
+
+   The objects in *methods* should be one of:
+
+   * :class:`selector` instances with a callable (that is, the first argument
+     to :class:`selector` must not be :data:`None`).
+
+   * :class:`classmethod` or :class:`staticmethod` instances that wrap a
+     function object.
+
+   * functions
+
+   * unbound methods
+
+   For the last two the method selector is calculated using the regular
+   algoritm for this (e.g. as if ``selector(item)`` was called). The last
+   two are instance methods by default, but automaticly made class methods
+   when the class (or a superclass) has a class method with the same
+   selector.
+
+.. function:: classAddMethod(cls, name, method)
+
+   Adds function *method* as selector *name* to the given class. When *method*
+   is a selector the signature and class-method-ness are copied from the selector.
+
+   .. note::
+
+      Adding a selector that's defined in Objective-C to another class will raise
+      an exception.
+
+.. class:: Category
+
+   A helper class for adding a category to an existing Objecive-C class (subclass
+   of :c:type:`NSObject`).
+
+   Usage::
+
+       class NSObject (Category(NSObject)):
+          def method(self):
+              pass
+
+   The metaclass uses :func:`classAddMethods` to add the methods in the category
+   body to the base class.
+   
+   The name of the class must be the same as the argument to :class:`Category`.
+
+
+Plugin bundles
+..............
+
+
+.. function:: currentBundle
+
+   During module initialization this function returns an NSBundle object for
+   the current bundle. This works for application as well as plug-ins created 
+   using `py2app <http://packages.python.org/py2app>`_.
+
+   After module initialization use ``NSBundle.bundleForClass_(ClassInYourBundle)``
+   to get the bundle.
+
+.. function:: registerPlugin(pluginName)
+
+   .. deprecated:: 2.3
+      use :func:`currentBundle` instead
+
+   Register the current py2app plugin by named and return its bundle.
+
+.. function:: pluginBundle(pluginName)
+
+   .. deprecated:: 2.3
+      use :func:`currentBundle` instead
+
+   Return the main bundle for a named plugin. This should only be used
+   after it has been register with :func:`registerPlugin`.
+
+
+
+Memory management
+.................
+
+PyObjC automaticly manages Cocoa reference counts for you, the functions 
+in this section help in finetuning this behaviour.
+
+.. function:: recycleAutoreleasePool()
+
+   Flush the NSAutoreleasePool that PyObjC creates on import. Use this
+   before entering the application main loop when you do a lot of work
+   before starting the main loop.
+
+.. function:: removeAutoreleasePool()
+
+   Use this in plugin bundles to remove the release pool that PyObjC creates
+   on import. In plugins this pool will interact in unwanted ways with the
+   embedding application.
+
+
+Test support
+............
+
+The functions in this section are present as support code for PyObjC's 
+unittests and are not part of the stable API. Please let us know if you
+use these functions in your code.
+
+.. function:: splitSignature(typestring)
+
+   Split an encoded Objective-C signature string into the
+   encoding strings for seperate types.
+
+   :param typestring: an encoded method signature (byte string)
+   :return: list of type signatures
+   :type typestring: byte string
+   :rtype: list of byte strings
+
+
+.. function:: splitStructSignature(typestring)
+
+   Returns (structname, fields). *Structname* is a string or :data:`None` and
+   *fields* is a list of (name, typestr) values. The *name* is a string or
+   :data:`None` and the *typestr* is a byte string.
+
+   Raises :exc:`ValueError` when the type is not the type string for a struct
+   type.
+
+
+.. function:: repythonify(object [, type])
+
+   Internal API for converting an object to a given Objetive-C type
+   and converting it back again.
+
+
+Framework wrappers
+..................
+
+.. function:: pyobjc_id(obj)
+
+   Returns the address of the underlying object as an integer.
+
+   .. note::
+
+      This is basicly the same as :func:`id`, but for the Objective-C 
+      object wrapped by PyObjC instead of python objects.
+
+.. function:: loadBundle(module_name, module_globals [, bundle_path [, bundle_identifier[, scan_classes]]])
+
+   Load the bundle specified by *bundle_path* or *bundle_identifier* and add the classes
+   in the bundle to *module_globals*. The classes are not added to the *module_globals* when
+   *scan_classes* is :data:`False` (it defaults to :data:`True`).
+
+   If both a *bundle_path* and *bundle_identifier* are specified the function first tries
+   to locate the bundle using the identifier and then using the path.
+
+   When *bundle_identifier* is specified the bundle is located using ``[NSBundle +bundleWithIdentifier:]``,
+   and when *bundle_path* is specified the bundle is located using ``[NSBundle +bundleWithPath:]``.
+
+   .. note::
+
+      *bundle_path* must be an absolute path.
+
+   .. note::
+      
+      The current implementation loads *all* Objective-C classes into *module_globals*, as
+      testing if a class is located in a specific bundle is fairly expensive and slowed down
+      application initialization too much.
+
+   
+.. function:: registerCFSignature(name, encoding, typeId[, tollfreeName])
+
+   Register a CoreFoundation based type with the bridge. If *tollfreeName* is specified
+   the type is tollfree bridged to that Objective-C class. 
+
+   The value of *typeId* is :data:`None` for tollfree bridged types, and the result
+   of the "GetTypeID" function for the type for other types.
+
+   Returns the class object for the registerd type.
+
+
+.. function:: loadBundleVariables(bundle, module_globals, variableInfo[, skip_undefined])
+
+   Loads a list of global variables (constants) from a bundle and adds proxy objects for
+   them to the *module_globals* dictionary. If *skip_undefined* is :data:`True` (the default)
+   the function will skip entries that don't refer to existing variables, otherwise it 
+   raises an :exc:`error` exception for these variables.
+
+   *variableInfo* is a sequence of variable descriptions. Every description is a tuple
+   of two elements: the variable name (a string) and the type encoding for the variable
+   (a byte string).
+
+
+.. function:: loadSpecialVar(bundle, module_globals, typeid, name[, skip_undefined])
+
+   This function loads a global variable from a bundle and adds it to the *module_globals*
+   dictionary. The variable should be a CoreFoundation based type, with a value that 
+   is not a valid pointer.
+
+   If *skip_undefined* is :data:`True` (the default) the function won't raise and exception
+   when the variable is not present. Otherwise the function will raise an :exc:`error` exception.
+
+
+.. function:: loadBundleFunctions(bundle, module_globals, functionInfo[, skip_undefined])
+
+   Loads a list of functions from a bundle and adds proxy objects for
+   them to the *module_globals* dictionary. If *skip_undefined* is :data:`True` (the default)
+   the function will skip entries that don't refer to existing functions, otherwise it 
+   raises an :exc:`error` exception for these functions.
+
+   *bundle* is either an *NSBundle* instance, or :data:`None`. When a bundle is specified
+   the function is looked up in that bundle, otherwise the function is looked up in
+   any bundle (including the main program and Python extensions).
+
+   *functionInfo* is a sequence of function descriptions. Every description is a tuple
+   of two or four elements: the function name (a string) and signature (a byte string) and 
+   optionally a value for the "\__doc__" attribute and a metadata dictionary.
+
+
+.. function:: loadFunctionList(list, module_globals, functionInfo[, skip_undefined])
+
+   Simular to :func:`loadBundleFunctions`, but loads the functions from *list* instead
+   of a bundle.
+
+   *List* should be a capsule object with tag "objc.__inline__" and the value should
+   be a pointer to an array of structs with the following definition:
+
+   .. sourcecode:: objective-c
+
+      struct function {
+          char*  name;
+          void   (*function)(void);
+      };
+
+   ..  x*
+
+   The last item in the array must have a :c:data:`NULL` pointer in the name field.
+
+
+.. function:: createOpaquePointerType(name, typestr, doc)
+
+   Return a wrapper type for opaque pointers ("handles") of a given type. 
+   The type will be registered with the bridge and will be used to wrap 
+   values with the given type signature.
+
+.. function:: createStructType(name, typestr, fieldnames, doc[, pack])
+
+   Create a type to wrap structs with a given name and type signature, this
+   type will be used by the bridge to convert values of this structure to Python.
+
+   This also adds a class method named *name* to :class:`objc.ivar`. This class
+   method creates a new instance variable with the struct type as its type.
+
+   * *name* is a string with the name of the structure, for example "NSPoint".
+
+   * *typestr* is the encoded type of the structure and can optionally 
+     contain embedded field names
+
+   * *fieldnames* is a list with the field names, the value can be :data:`None`
+     when the *typestr* contains embedded field names.
+
+   * *doc* is the value of \__doc__ for the new type
+
+   * *pack* can be used to specify the value of "#pragma pack" for the structure
+     (default is to use the default platform packing for structures).
+
+
+   The created type behaves itself simular to a mutable :func:`namedtuple <collections.namedtuple>`,
+   that is items can be accessed both using attribute access and using the sequence interface.
+
+   An example::
+
+      Point = objc.createStructType("Point", b"{Point=dd}", ["x", "y"])
+
+      p = Point(3.0, 4.0)
+
+      # Set the X field in two ways:
+      p.x = 5
+      p[0] = 6
+
+   The generated type als has a number of methods:
+
+   * *_asdict()*:  Returns a dict that maps from field names to attribute values
+
+   * *_replace(**kwds)*: Return a copy of the struct and replace attribute values with values from the keyword arguments
+
+   * *copy()*: Return a copy of the struct. If an attribute is another struct that attribute gets copied as well, other attributes
+     are not copied. That is, struct types are deep copied other types are shallow copied.
+
+   And the following attributes are present:
+
+   * *_fields*: A list of field names
+
+   * *__typestr__*: The Objective-C type encoding for the struct (without embedded field names)
+
+
+   .. versionchanged:: 2.5
+      The function creates a class method on :class:`objc.ivar`.
+
+   .. versionchanged:: 2.5
+      The type now implements the "_asdict" and "_replace" methods that
+      are also present on :func:`collections.namedtuple` types. The
+      attribute "_fields" was added as well.
+
+.. function:: registerStructAlias(typestr, structType)
+
+   Tell the brige that structures with encoding *typestr* should also be 
+   coverted to Python using *structType* (a type created using :func:`createStructType`).
+
+   .. deprecated:: 2.5
+      Use :func:`createStructAlias` instead.
+
+.. function:: createStructAlias(name, typestr, structType)
+
+   Tell the brige that structures with encoding *typestr* should also be 
+   coverted to Python using *structType* (a type created using 
+   :func:`createStructType`).
+
+   This also adds a class method named *name* to :class:`objc.ivar`. This class
+   method creates a new instance variable with the struct type as its type.
+
+   .. versionadded: 2.5
+
+.. function:: registerMetaDataForSelector(class\_, selector, metadata)
+
+   Register a metadata structure for the given selector.
+
+   .. todo:: insert reference to metadata documentation
+
+.. function:: registerListType(type)
+
+   Register *type* as a list-like type that will be bridged to Objective-C as an NSArray subclass.
+
+
+.. function:: registerMappingType(type)
+
+   Register *type* as a dict-like type that will be bridged to Objective-C as an NSDictionary subclass.
+
+
+.. function:: addConvenienceForSelector(selector, methods)
+
+    Add a list of method to every class that has *selector* as a selector.
+    These additional methods are not added to the Objective-C class, but are 
+    only visibile in Python code.
+
+    The *methods* argument is a list of tuples (methodname, function).
+
+   .. deprecated:: 2.5
+
+      This function is deprecated, future versions of PyObjC will use a different way
+      to initialise classes that will require us to remove this function.
+
+
+.. function:: addConvenienceForClass(classname, method)
+
+    Add a list of method the named class when that class is initialized, the class
+    need not be loaded at the time of this call. These additional methods are not
+    added to the Objective-C class, but are only visibile in Python code.
+
+    The *methods* argument is a list of tuples (methodname, function).
+
+
+.. function:: _setClassSetUpHook
+
+   This is a private hook that is called during the creation of a subclass.
+
+   .. warning:: 
+      This hook is not part of the stable API.  
+
+   .. versionadded:: 2.3
+
+.. function:: _setClassExtender
+
+   This is a private hook that's called during the creation of the proxy for
+   an Objective-C class.
+
+   .. warning:: 
+      This hook is not part of the stable API.
+   
+   .. versionadded:: 2.2
+
+   .. versionchanged:: 2.3
+      In version 2.2 the hook gets called any time the bridge rescans
+      a class, in 2.3 the hook only gets called during initial construction
+      and has less oportunity to change things.
+
+
+Types
+-----
+
+.. class:: objc_class
+
+   This class is the metatype for Objective-C classes and provides no user-visible
+   behavior.
+
+.. class:: objc_object
+
+   This class is the root class for Objective-C classes, that is all wrappers for
+   Objective-C classes are a subclass of this class. It is not possible to instantiate
+   instances of Objective-C classes by using the class as a callable, instances are
+   created using the standard Objective-C mechanisms instead.
+
+   .. data:: pyobjc_ISA
+
+      Read-only property that returns the current Objective-C classes of an object.
+
+   .. data:: pyobjc_instanceMethods
+
+      Read-only property that provides explicit access to just the instance methods
+      of an object.
+
+   .. data:: \__block_signature__
+
+      Property with the type signature for calling a block, or :data:`None`.
+
+   .. method:: __cobject__()
+
+      Returns a capsule object with identifier "objc.__object__" and the a reference
+      to the Objective-C object as the value.
+
+   .. method:: __reduce__()
+
+      This method ensures that Objective-C objects will not be pickled unless the subclass
+      explictly implements the pickle protocol. This is needed because the pickle will
+      write an incomplete serialization of Objective-C objects for protocol 2 or later.
+
+   .. note::
+
+      The wrapper classes for the :c:type:`NSString` class cluster aren't subclasses
+      of :class:`objc_object`, but are subclasses of the builtin :class:`unicode` type
+      (:class:`str:` in Python 3).
+
+.. class:: pyobjc_unicode
+
+   This class is used to wrap instances of the :c:type:`NSString` class cluster and is
+   a subclass of the builtin Unicode type (:class:`unicode` for python 2 and :class:`str` 
+   for Python 3).
+
+   Methods of the underlying :c:type:`NSString` class can be accessed at as methods
+   of the python type, unless they have the same name as a method of the built-in Unicode
+   type.
+
+   .. method:: nsstring
+
+      Returns an instance of a subclass of :class:`objc_object` that represents the
+      string. This provides full access to the Cocoa string API, but without easy
+      interoperability with Python APIs.
+
+
+   .. warning::
+
+      Instances of :c:type:`NSString` can be mutable. Mutations to mutable Cocoa
+      strings are not reflected in instances of :class:`pyobjc_unicode`, use
+      :meth:`nsstring` and explict conversion to the built-in unicode type when
+      you work with mutable :c:type:`NSString` values.
+
+   .. note::
+
+      Cocoa strings are wrapped using a subclass of the built-in unicode string
+      to get better interaction between Python and Cocoa. Because Cocoa strings are
+      instances of the built-in unicode type they can be passed to functions in
+      extension modules that expect unicode arguments (in particular the file 
+      system access APIs such as :func:`open`).
+
+
+.. class:: selector(function[, selector[, signature[, isClassMethod[, returnType[, argumentTypes[, isRequired]]]]]])
+
+   This type is used to represent an Objective-C method. 
+
+   :param function:  The Python callable that is used for the method. Can be a :class:`classmethod` , but not a :class:`staticmethod`.
+   :param selector:  The Objective-C selector for the method. The default is calculated from the \__name__ attribute for *function*
+   :param signature: The type encoding for the method, the default signature assumes that all arguments and the result are objects
+                     (or 'void' when the function does not contain a return statement with a value).
+   :param isClassMethod: Used to specify if a method is a class method (default is :data:`True` if *function* is a :class:`classmethod`
+                     and :data:`False` otherwise)
+   :param returnType: Alternative method for specifying the method return type, using the syntax of :c:func:`Py_BuildValue`.
+   :param argumentTypes: Alternative method for specifying argument types, using the syntax of :c:func:`Py_BuildValue`.
+   :param isRequired:    Specify if the method is required (defaults to :data:`True`), used in the definition of protocols.
+
+   The arguments *returnType* and *argumentTypes* are deprecated in PyObjC 2.5, they are confusing and can only specify
+   a subset of types.
+
+   .. data:: callable
+
+      Read-only property with access to the underlying callable (the *function* argument to the constructor).
+
+   .. data:: __doc__
+
+      Documentation string for the selector
+
+   .. method:: __metadata__
+
+      Returns a copy of the metadata dictionary for the selector. 
+
+      .. todo:: insert link to metadata description
+
+
+.. class:: ivar([name[, type[, isOutlet]]])
+
+   Creates a descriptor for accessing an Objective-C instance variable. This should only
+   be used in the definition of an Objective-C subclass, the bridge will use this information
+   to create an instance variable with the same name on the Objective-C class itself.
+
+   :param name: Name of the instance variable. The name defaults to the name the instance
+                variable is bound to in a class definition.
+
+   :param type: Type encoding for the instance varialble. Defaults to :data:`_C_ID` (that is,
+                an object)
+
+   :param isOutlet: If :data:`True` the instance variable is used as an outlet, by default
+                the instance variable is not an outlet.
+
+   .. note::
+      Sharing an ivar object between multiple class definitions is not supported.
+
+
+   Instances of :class:`ivar` have a number of attributes that help with introspection:
+   
+   * *__typestr__*: The type encoding of the Objective-C type of the variable
+
+   * *__name__*: The Objective-C name of the variable
+
+   * *__isOutlet__*: :data:`True` if the variable is an :func:`IBOutlet`
+
+   * *__isSlot__*: :data:`True` if the variable is a Python slot.
+
+   .. note::
+
+      You cannot access these attributes  through an Objective-C instance, you have to access
+      them through the class object. That's because :class:`ivar` is a data descriptor.
+
+   .. seealso::
+
+      Function :func:`IBOutlet`
+         Definition of outlets.
+
+
+.. class:: informal_protocol(name, selector_list)
+
+   This class is used to specify which methods are part of an informal protocol
+   in Objective-C. Informal protocols are a documentation construct in Objective-C and
+   as such are not present in the Objective-C runtime (as opposed to formal protocols).
+
+   Informal protocols are used by the bridge to automaticly update method signatures when
+   a class appears to implement an informal protocol. This makes it possible the define
+   a large subset of Cocoa functionality without manually setting method signatures.
+
+   :param name: Name of the protocol
+   :param selector_list: A sequence of :class:`selector` instances, all of which should have no callable.
+
+   .. data:: __name__
+
+      Read-only property with the protocol name
+
+   .. data:: selectors
+
+      Read-only property with the sequence of selectors for this protocol
+
+
+.. class:: formal_protocol(name, supers, selector_list)
+
+   This class is used to represent formal protocols in Python, and is comparabile with the
+   "@protocol" construct in Objective-C.
+
+   :param name:     The name of the protocol
+   :param supers:   A list of protocols this protocol inherits from
+   :param selector_list: A sequence of :class:`selector` instances, all of which should have no callable.
+
+   .. note::
+
+      Constructing new protocols is supported on a subset of Mac OS X platforms:
+
+      * All 32-bit programs
+
+      * 64-bit programs starting from Mac OS X 10.7, but only when PyObjC was build with
+        the 10.7 SDK (or later)
+
+   .. data:: __name__
+
+      Read-only property with the name of the protocol
+
+   .. method:: name
+
+      Returns the name of the protocol
+
+   .. method:: conformsTo_(proto)
+
+      Returns :data:`True` if this protocol conforms to protocol *proto*, returns :data:`False` otherwise.
+
+   .. method:: descriptionForInstanceMethod_(selector)
+
+      Returns a tuple with 2 byte strings: the selector name and the type signature for the selector.
+
+      Returns :data:`None` when the selector is not part of the protocol.
+
+   .. method:: descriptionForClassMethod_(selector)
+
+      Returns a tuple with 2 byte strings: the selector name and the type signature for the selector.
+
+      Returns :data:`None` when the selector is not part of the protocol.
+
+   .. method:: instanceMethods()
+
+      Returns a list of instance methods in this protocol.
+
+   .. method:: classMethods()
+
+      Returns a list of instance methods in this protocol.
+
+   .. note::
+
+      The interface of this class gives the impression that a protocol instance is an Objective-C
+      object. That was true in earlier versions of Mac OS X, but not in more recent versions.
+
+
+.. class:: varlist
+
+   A C array of unspecified length. Instances of this type cannot be created in Python code.
+
+   This type is used when the API does not specify the amount of items in an array in a way
+   that is usable by the bridge.
+
+   .. warning:: 
+
+      Access through a :class:`varlist` object can easily read beyond the end of the
+      wrapped C array.  Read the Apple documentation for APIs that return a varlist to
+      determine how many elements you can safely access.
+
+   .. method:: as_tuple(count)
+
+      Returns a tuple containing the first *count* elements of the array.
+
+   .. method:: __getitem__(index)
+    
+      Returns the value of the *index*-th element of the array. Supports numeric
+      indexes as well as slices.
+
+   .. method:: __setitem__(index, value)
+
+      Sets the value of the *index*-th element of the array. Supports numeric
+      indexes as well as slices (but assigning to a slice is only possible when
+      that does not resize the array).
+
+
+.. class:: function
+
+   Instances of this class represent global functions from Cocoa frameworks. These
+   objects are created using :func:`loadBundleFunctions` and :func:`loadFunctionList`.
+
+   .. data:: __doc__
+
+      Read-only property with the documentation string for the function.
+
+   .. data:: __name__
+
+      Read-only property with the name of the function
+
+   .. data:: __module__
+
+      Read-write property with the module that defined the function
+
+   .. method:: __metadata__
+
+      Returns a copy of the metadata dictionary for the selector. 
+
+      .. todo:: insert link to metadata description
+
+
+.. class:: IMP
+
+   This class is used to represent the actual implementation of an Objective-C
+   method (basicly a C function). Instances behave the same as unbound methods:
+   you can call them but need to specify the "self" argument.
+
+   .. data:: isAlloc
+
+      Read-only attribute that specifies if the IMP is an allocator (that is,
+      the implementation of "+alloc" or one of its variant)
+
+   .. data:: isClassMethod
+
+      Read-only attribute that specified if the IMP is for a class method.
+
+   .. data:: signature
+
+      Read-only attribute with the type encoding for the IMP.
+
+   .. data:: selector
+
+      Read-only attribute with the selector for the method that this IMP
+      is associated with.
+
+   .. data:: __name__
+
+      Alias for :data:`selector`.
+
+   .. method:: __metadata__
+
+      Returns a copy of the metadata dictionary for the selector. 
+
+      .. todo:: insert link to metadata description
+
+
+.. class:: super
+
+   This is a subclass of :class:`super <__builtin__.super>` that works
+   properly for Objective-C classes as well as regular Python classes.
+
+   .. note:: 
+   
+      The statement :samp:`from {Framework} import \*` will replace the 
+      built-in :class:`super <__builtin__.super>` by this class.
+
+Constants
+---------
+
+.. data:: nil
+
+   Alias for :const:`None`, for easier translation of existing Objective-C
+   code.
+
+.. data:: YES
+
+   Alias for :const:`True`, for easier translation of existing Objective-C
+   code.
+
+.. data:: NO
+
+   Alias for :const:`False`, for easier translation of existing Objective-C
+   code.
+
+.. data:: NULL
+
+   TODO: add description of pass by reference arguments and the 
+   difference between None and NULL
+
+.. data:: MAC_OS_X_VERSION_MAX_ALLOWED
+
+   The value of :c:data:`MAC_OS_X_VERSION_MAX_ALLOWED` when PyObjC was
+   compiled.
+
+.. data:: MAC_OS_X_VERSION_MIN_REQUIRED
+
+   The value of :c:data:`MAC_OS_X_VERSION_MIN_REQUIRED` when PyObjC was
+   compiled.
+
+.. data:: MAC_OS_X_VERSION_10_N
+
+   There are currently 6 constants of this form, for ``N`` from 1 to 6,
+   and these have the same value as the Objective-C constant of the same
+   name.
+ 
+.. data:: platform
+
+   This always has the value "MACOSX".
+
+
+
+Objective-C type strings
+------------------------
+
+The Objective-C runtime and the PyObjC bridge represent the types of
+instance variables and methods arguments and return values as a string
+with a compact representation. The Python representation of that string is
+a byte string (that is type :class:`bytes` in Python 3.x and :class:`str`
+in Python 2.x).
+
+Basic types
+............
+
+The representation for basic types is a single character, the table below
+lists symbolic constants in the for those constants.
+
+======================== =================================================
+Name                     Objective-C type
+======================== =================================================
+:const:`_C_ID`           :c:type:`id` (an Objective-C instance)
+------------------------ ------------------------------------------------- 
+:const:`_C_CLASS`        an Objective-C class
+------------------------ -------------------------------------------------
+:const:`_C_SEL`          a method selector
+------------------------ -------------------------------------------------
+:const:`_C_CHR`          :c:type:`char`
+------------------------ -------------------------------------------------
+:const:`_C_UCHR`         :c:type:`unsigned char`
+------------------------ -------------------------------------------------
+:const:`_C_SHT`          :c:type:`short`
+------------------------ -------------------------------------------------
+:const:`_C_USHT`         :c:type:`unsigned short`
+------------------------ -------------------------------------------------
+:const:`_C_BOOL`         :c:type:`bool`  (or :c:type:`_Bool`)
+------------------------ -------------------------------------------------
+:const:`_C_INT`          :c:type:`int`
+------------------------ -------------------------------------------------
+:const:`_C_UINT`         :c:type:`unsigned int`
+------------------------ -------------------------------------------------
+:const:`_C_LNG`          :c:type:`long`
+------------------------ -------------------------------------------------
+:const:`_C_ULNG`         :c:type:`unsigned long`
+------------------------ -------------------------------------------------
+:const:`_C_LNG_LNG`      :c:type:`long long`
+------------------------ -------------------------------------------------
+:const:`_C_ULNG_LNG`     :c:type:`unsigned long long`
+------------------------ -------------------------------------------------
+:const:`_C_FLT`          :c:type:`float`
+------------------------ -------------------------------------------------
+:const:`_C_DBL`          :c:type:`double`
+------------------------ -------------------------------------------------
+:const:`_C_VOID`         :c:type:`void`
+------------------------ -------------------------------------------------
+:const:`_C_UNDEF`        "other" (such a function)
+------------------------ -------------------------------------------------
+:const:`_C_CHARPTR`      C string (:c:type:`char*`)
+------------------------ -------------------------------------------------
+:const:`_C_NSBOOL`       :c:type:`BOOL`
+------------------------ -------------------------------------------------
+:const:`_C_UNICHAR`      :c:type:`UniChar`
+------------------------ -------------------------------------------------
+:const:`_C_CHAR_AS_TEXT` :c:type:`char` when uses as text or a byte array
+------------------------ -------------------------------------------------
+:const:`_C_CHAR_AS_INT`  :c:type:`int8_t` (or :c:type:`char` when 
+                    used as a number)
+======================== =================================================
+
+The values :const:`_C_NSBOOL`, :const:`_C_UNICHAR`, :const:`_C_CHAR_AS_TEXT`
+and :const:`_C_CHAR_AS_INT` are inventions of PyObjC and are not used in
+the Objective-C runtime.
+
+Complex types
+..............
+
+More complex types can be represented using longer type strings: 
+
+* a pointer to some type is :const:`_C_PTR` followed by the type string 
+  of the pointed-to type.
+
+* a bitfield in a structure is represented as :const:`_C_BFLD` followed
+  by an integer with the number of bits. 
+  
+  Note that PyObjC cannot convert bitfields at this time.
+
+* a C structure is represented as :const:`_C_STRUCT_B` followed by the
+  struct name, followed by :const:`'='`, followed by the encoded types of
+  all fields followed by :const:`_C_STRUCT_E`. The field name (including the
+  closing equals sign) is optional.
+
+* a C union is represented as :const:`_C_UNION_B` followed by the
+  struct name, followed by :const:`'='`, followed by the encoded types of
+  all fields followed by :const:`_C_UNION_E`. The field name (including the
+  closing equals sign) is optional.
+
+  Note that PyObjC cannot convert C unions at this time.
+
+* a C array is represented as :const:`_C_ARY_B` followed by an integer 
+  representing the number of items followed by the encoded element type,
+  followed by :const:`_C_ARY_E`.
+
+* The C construct 'const' is mapped to :const:`_C_CONST`, that is a 
+  :c:type:`const char*` is represented as :const:`_C_CONST` + :const:`_C_CHARPTR`.
+
+Additional annotations for method and function arguments
+........................................................
+
+Method arguments can have prefixes that closer describe their functionality.
+Those prefixes are inheritted from Distributed Objects are not used by the
+Objective-C runtime, but are used by PyObjC.
+
+* When a pointer argument is an input argument it is prefixed by
+  :const:`_C_IN`.
+
+* When a pointer argument is an output argument it is prefixed by
+  :const:`_C_OUT`.
+
+* When a pointer argument is an input and output argument it is prefixed 
+  by :const:`_C_INOUT`.
+
+* Distributed objects uses the prefix :const:`_C_BYCOPY` to tell that a 
+  value should be copied to the other side instead of sending a proxy
+  reference. This is not used by PyObjC.
+
+* Distributed objects uses the prefix :const:`_C_ONEWAY` on the method return
+  type to tell that the method result is not used and the caller should not
+  wait for a result from the other side. This is not used by PyObjC.
+
+When a pointer argument to a function prefixed by :const:`_C_IN`, 
+:const:`_C_OUT` or :const:`_C_INOUT` the brige assumes that it is a pass by
+reference argument (that is, a pointer to a single value), unless other 
+information is provided to the bridge.
+
+TODO: Write how to write Objective-C code to ensure that the right prefixes
+are added by the compiler.
+
+Special encoded types
+.....................
+
+The table below shows constants for a number of C types that are used 
+in Cocoa but are not basic C types.
+
+  ======================= ==============================
+  Constant                Objective-C type
+  ======================= ==============================
+  :const:`_C_CFTYPEID`    :c:type:`CFTypeID`
+  ----------------------- ------------------------------
+  :const:`_C_NSInteger`   :c:type:`NSInteger`
+  ----------------------- ------------------------------
+  :const:`_C_NSUInteger`  :c:type:`NSUInteger`
+  ----------------------- ------------------------------
+  :const:`_C_CFIndex`     :c:type:`CFIndex`
+  ----------------------- ------------------------------
+  :const:`_C_CGFloat`     :c:type:`CGFloat`
+  ----------------------- ------------------------------
+  :const:`_sockaddr_type` :c:type:`struct sockaddr`
+  ======================= ==============================
+
+
+Context pointers
+----------------
+
+A number of Objective-C APIs have one argument that is a context pointer,
+which is a :c:type:`void*`. In Objective-C your can pass a pointer to an
+arbitrary value, in Python this must be an integer.
+
+PyObjC provides a :data:`context` object that can be used to allocate
+unique integers and map those to objects.
+
+.. function:: context.register(value)
+
+   Add a value to the context registry.
+