1===============================
2PyObjCTools: The PyObjC Toolbox
3===============================
4
5Introduction
6------------
7
8The package ``PyObjCTools`` contains a number of (basically unrelated) modules
9with useful functionality. These have been placed inside a module to avoid
10cluttering the global namespace.
11
12The rest of this document provides documentation for these modules, but lets
13start with a short overview.
14
15* ``PyObjCTools.AppHelper``
16
17Utility functions for use with the ``AppKit`` module.
18
19* ``PyObjCTools.Conversion``
20
21Functions for converting between Cocoa and pure Python data structures.
22
23* ``PyObjCTools.KeyValueCoding``
24
25A Python API for working with `Key-Value Coding`__. 
26
27.. __: http://developer.apple.com/documentation/Cocoa/Conceptual/KeyValueCoding/
28
29* ``PyObjCTools.NibClassBuilder``
30
31Module containing a magic super-class that can read information about the
32actual super-class and implemented actions and outlets from a NIB file.
33
34* ``PyObjCTools.MachSignals``
35
36Module to make it possible to integrate signal handling into the main
37runloop.
38
39* ``PyObjCTools.Debugging``
40
41Allows logging of NSException stack traces.  This module should only be used
42during development.
43
44* ``PyObjCTools.Signals``
45
46Module that tries to print useful information when the program gets a fatal
47exception. This module should only be used during development.
48
49* ``PyObjCTools.XcodeSupport``
50
51Used by the PyObjC Xcode templates to derive py2app options from an Xcode
52project file.
53
54
55``PyObjCTools.AppHelper``
56.........................
57
58This module exports functions that are useful when working with the
59``AppKit`` framework (or more generally, run loops).
60
61* ``callAfter(func, *args, **kwargs) -> None``
62
63  Call a function on the main thread.  Returns immediately.
64
65* ``callLater(delay, func, *args, **kwargs) -> None``
66
67  Call a function on the main thread after a delay.  Returns immediately.
68
69* ``endSheetMethod(method) -> selector``
70
71  Convert a method to a form that is suitable to use as the delegate callback
72  for sheet methods.
73
74* ``stopEventLoop() -> None``
75
76  Stops the event loop (if started by ``runConsoleEventLoop``) or sends the
77  ``NSApplication`` a ``terminate:`` message.
78
79* ``runConsoleEventLoop(argv=None, installInterrupt=False, mode=NSDefaultRunLoopMode) -> None``
80
81  Run a ``NSRunLoop`` in a stoppable way (with ``stopEventLoop``).
82
83* ``runEventLoop(argv=None, unexpectedErrorAlert=unexpectedErrorAlert, installInterrupt=None, pdb=None, main=NSApplicationMain) -> None``
84
85  Run the event loop using ``NSApplicationMain`` and ask the user if we should
86  continue if an exception is caught.
87
88  This function doesn't return unless it throws an exception.
89
90
91``PyObjCTools.Conversion``
92.............................
93
94Functions for converting between Cocoa and pure Python data structures.
95
96* ``propertyListFromPythonCollection(pyCol, conversionHelper=None) -> ocCol``
97
98  Convert a Python collection (dictionary, array, tuple, string) into an 
99  Objective-C collection.
100
101  If conversionHelper is defined, it must be a callable.  It will be called 
102  for any object encountered for which ``propertyListFromPythonCollection()``
103  cannot automatically convert the object.   The supplied helper function 
104  should convert the object and return the converted form.  If the conversion 
105  helper cannot convert the type, it should raise an exception or return None.
106
107* ``pythonCollectionFromPropertyList(ocCol, conversionHelper=None) -> pyCol``
108
109  Converts a Foundation based collection-- a property list-- into a Python 
110  collection.  Like ``propertyListFromPythonCollection()``, ``conversionHelper``
111  is an optional callable that will be invoked any time an encountered object 
112  cannot be converted.
113
114``PyObjCTools.KeyValueCoding``
115..............................
116
117A module for working with Key-Value Coding in Python. Key-Value Coding is
118explained `on the Apple website`__
119
120.. __: http://developer.apple.com/documentation/Cocoa/Conceptual/KeyValueCoding/
121
122This module provides a Python interface to some of that functionality. The
123interface is modeled on the ``getattr`` and ``setattr`` functions.
124
125* ``getKey(object, key) -> value``
126
127    Get the attribute referenced by 'key'. The key is used
128    to build the name of an attribute, or attribute accessor method.
129
130    The following attributes and accesors are tried (in this order):
131
132    - Accessor 'getKey'
133    - Accesoor 'get_key'
134    - Accessor or attribute 'key'
135    - Accessor or attribute 'isKey'
136    - Attribute '_key'
137
138    If none of these exist, raise KeyError
139
140* ``getKeyPath(object, keypath) -> value``
141
142  Like ``getKey`` but using a key path. The ``keypath`` is a sequence of keys
143  separated by dots. It calls ``getKey`` to follow the path and returns the
144  final value.
145
146* ``setKey(object, key, value) -> None``
147
148  Set the value of ``key`` to ``value``.
149
150  The following values are used for setting the value for a key named ``key``
151  (first match wins):
152
153  - Call ``object.set_key(value)``
154
155  - Call ``object.setKey(value)``
156
157  - Call ``object._set_key(value)``
158
159  - Call ``object._setKey(value)``
160
161  - Check if ``_key`` is an attribute and if so, set its value
162
163  - Try to set the attribute ``key``.
164
165  Raises ``KeyError`` if the key cannot be changed.
166
167* ``setKeyPath(object, keypath, value) -> None``
168
169  The same as ``setKey``, but now using a key path. A key path is a sequence
170  of keys separated by dots. The ``getKey`` function is used to traverse 
171  the path up to the last item, and then ``setKey`` is used to change the value.
172
173PyObjCTools.NibClassBuilder
174...........................
175
176Extracting class definitions from nibs
177++++++++++++++++++++++++++++++++++++++
178
179The module maintains a global set of class definitions, extracted from
180nibs. To add the classes from a nib to this set, use the ``extractClasses()``
181function. It can be called in two ways:
182
183- ``extractClasses(nibName, bundle=<current-bundle>)``
184
185  This finds the nib by name from a bundle. If no bundle
186  if given, the ``objc.currentBundle()`` is searched.
187
188- ``extractClasses(path=pathToNib)``
189
190  This uses an explicit path to a nib.
191
192``extractClasses()`` can be called multiple times for the same bundle: the
193results are cached so no almost extra overhead is caused.
194
195Using the class definitions
196+++++++++++++++++++++++++++
197
198The module contains a "magic" base (super) class called ``AutoBaseClass``.
199Subclassing ``AutoBaseClass`` will invoke some magic that will look up the
200proper base class in the class definitions extracted from the nib(s).
201If you use multiple inheritance to use Cocoa's "informal protocols",
202you *must* list ``AutoBaseClass`` as the first base class. For example::
203
204    class PyModel(AutoBaseClass, NSTableSource):
205        ...
206
207
208The ``NibInfo`` class
209+++++++++++++++++++++
210
211The parsing of nibs and collecting the class definition is done by the
212``NibInfo`` class. You normally don't use it directly, but it's here if you
213have special needs.
214
215The command line tool
216+++++++++++++++++++++
217
218When run from the command line, this module invokes a simple command
219line program, which you feed paths to nibs. This will print a Python
220template for all classes defined in the nib(s). For more documentation,
221see the commandline_doc variable, or simply run the program without
222arguments. It also contains a simple test program.
223
224PyObjCTools.Signals
225...................
226
227This module provides two functions that can be useful while investigating
228random crashes of a PyObjC program. These crashes are often caused by 
229Objective-C style weak references or incorrectly implemented protocols.
230
231- ``dumpStackOnFatalSignal()``
232
233  This function will install signal handlers that print a stack trace and
234  then re-raise the signal.
235
236- ``resetFatalSignals()``
237
238  Restores the signal handlers to the state they had before the call to
239  dumpStackOnFatalSignal.
240
241This module is not designed to provide fine grained control over signal 
242handling. Nor is it intended to be terribly robust. It may give useful
243information when your program gets unexpected signals, but it might just
244as easily cause a crash when such a signal gets in. 
245