1===============================
2Structure of the PyObjC package
3===============================
4
5Introduction
6------------
7
8This document gives an overview of the PyObjC for developers (of the package).
9
10One of the sections describes how all of it works, and some of the limitations.
11
12This document is a incomplete, it should be updated.
13
14
15Methods
16-------
17
18Classes are scanned for methods when the Python wrapper for a class is created.
19We then create Python wrappers for those methods.  This way users can use the
20normal Python introspection methods to check which methods are available.
21
22There are several occasions when these method tables are rescanned, because
23classes can grow new methods when categories are loaded into the runtime.
24Additionally, it is known that some Cocoa frameworks in Mac OS X change
25their method tables when the first instance is created.
26
27Subclassing
28-----------
29
30It is possible to subclass Objective-C classes from Python.  These classes
31end up in a structure containing both a Python type object and an Objective-C
32class.  Instances of these classes also contain both a Python instance and
33an Objective-C object.
34
35The first Python subclass of an Objective-C class introduces a new instance
36variable in the Objective-C object to store the pointer to the Python half of
37the cluster.  This variable is always referenced by name.  The Python half is 
38a subclass of ``objc_object`` that already contains a pointer to an Objective-C 
39object.  This first subclass also introduces a number of class and instance
40methods that the PyObjC bridge uses to maintain the illusion of a single
41object on both sides.  Check class-builder.m for details.
42
43
44Directory structure
45-------------------
46
47Doc/
48  Documentation
49
50Examples/
51  Example scripts and applets.
52
53Lib/
54  The pure Python parts of the packages that comprise PyObjC.  
55
56Modules/
57  Extension modules related to the packages in 'Lib'.
58
59libffi-src/
60  A local copy of libffi, the Foreign Function Interface library used by
61  PyObjC.
62
63Reference counts
64----------------
65
66The Objective-C rules for reference counts are pretty easy: A small number
67of class methods (``alloc``, ``allocWithZone:``, ``copy``, ...) transfer
68object ownership to the caller.  For all other objects you have to call
69``retain`` if you want to keep a reference.  This includes all factory
70methods, such as ``[NSString stringWithCString:"bla"]``!
71
72When programming Cocoa in Python, you rarely need to worry about
73reference counts: the ``objc`` module makes this completely transparent to
74user.  This is mostly implemented in ``[de]pythonify_c_value``.  Additonal
75code is needed when calling methods that transfer ownership of their return
76value (as described above) and when updating a instance variable in an
77Objective-C object (retain new and release old, in that order).  Both are
78implemented.
79
80Strings
81-------
82
83Python ``unicode`` instances are proxied by the ``OC_PythonUnicode`` subclass
84of ``NSString``.  This is a proxy, and will maintain the identity of the
85original ``unicode`` instance.
86
87``NSString`` instances are represented in Python as a subtype of ``unicode``:
88``objc.pyobjc_unicode``.  This performs a conversion, because Python's
89``unicode`` type is immutable, but it also maintains a *reference* to the
90original ``NSString``.  ``NSString`` and ``NSMutableString`` methods are
91available from the ``objc.pyobjc_unicode`` object, though they do not show up
92via Python's introspection mechanisms.  In order to get the latest Python
93representation of a ``NSMutableString``, use the return value of its ``self()``
94method.
95
96Python ``str`` instances are proxied by the ``OC_PythonString`` subclass of
97``NSString``.  This is a proxy, and will maintain the identity of the
98original ``str`` instance.  ``OC_PythonString`` will use the default encoding
99of ``NSString``, so its results might be surprising if you are using non-ASCII
100text.  It is recommended that you use ``unicode`` whenever possible.  In order
101to help you determine where you are not using ``unicode``, it is possible
102to trigger an ``objc.PyObjCStrBridgeWarning`` warning whenever a ``str``
103instance crosses the bridge:
104
105
106 .. sourcecode:: python
107
108      import objc
109      objc.setStrBridgeEnabled(False)
110
111To promote these to an exception, do the following:
112
113 .. sourcecode:: python
114
115      import objc
116      import warnings
117      warnings.filterwarnings('error', objc.PyObjCStrBridgeWarning)
118