=======================
PyObjC protocol support
=======================

Introduction
------------

Apple makes use of both formal and informal protocols in the Cocoa framework.
Formal protocols are those protocols that are implemented using Objective-C
protocols::

	@protocol NSFoo <NSSomeProtocol>
	-(int)doesIt;
	@end

Informal protocols on the other hand are purely documentation, the Objective-C 
compiler doesn't know about them. For end users the main difference between
formal and informal protocols is that you have to declare that you implement a
formal protocol and that formal protocols do not have optional methods.

Informal protocols and PyObjC
-----------------------------

PyObjC does have an explicit representation for informal protocols. This makes
it possible to use the protocol description to provide better error messages and
to automaticly deduce the method signatures for classes that implement an
informal protocol.

Informal protocols are represented using instances of 
``objc.informal_protocol``. These instances are automaticly added to a registry,
therefore it is not necessary to declare that you implement an informal 
protocol.

Formal protocols and PyObjC
---------------------------

PyObjC also has an explicit representation for formal protocols. 

Formal protocols are represented as instances of ``objc.formal_protocol``. 
Unlike informal protocols you have to declare that you implement a formal 
protocol to get all features of formal protocols. However, all formal protocols
in Cocoa are also described using ``objc.informal_protocol`` objects.

XXX: is this necessary? we could also use the same strategy as for informal
protocols, and drop the informal_protocol wrappers for formal protocols.

You can declare that you implement a formal protocol by using the protocol as
a mix-in::

	class MyLockingObject (NSObject, NSLocking):
		def lock(self): pass
		def unlock(self): pass

The class now formally implements the ``NSLocking`` protocol, you can check this
using the Objective-C introspection methods::

	>>> MyLockingObject.pyobjc_classMethods.conformsToProtocol_(NSLocking)
	1

This is useful for API's that require (and check) the implementation of formal
protocols.

XXX: might also be useful for Distributed Objects, create an example