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