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