========= Todo list ========= .. contents: Introduction ------------ This document contains an (incomplete) list of work items. TODO for 1.1 ------------ * Sync with latest libffi (optional) * Test on OSX 10.2 and create installer * Test on OSX 10.1 Important items --------------- Better documentation .................... There should be more developer documentation and end-user documentation is virtually non-existant. Related to this is the website: This should be filled. We should also add scripts to convert documentation to a format that is useable on the website. Also needed: document listing the differences between Objective-C Cocoa and Python Cocoa: which functions/methods are not available, list differences in arguments (e.g. NSBeginAlertSheet has a variable number of arguments in Objective-C, the format-arguments are not present in Python). Multi-threading support ....................... Thanks to the autoGIL module the GIL is given up when the main runloop sleeps. We could give up the GIL before calling into Objective-C, but that requires a lot of work for minimal advantages. Test suite .......... The test suite needs to be enhanced. * Tests that exercise Key-Value Observing in a way that crashes older versions of PyObjC. * tests for all functions in ``Modules/*/*Mapping*.m`` (inclusing IMPs) * tests for all non-generated function wrappers (and some for the generated functions as well, just in case the generator script is buggy) * tests where Python implementation of method with output arguments returns the wrong value (type, number of values) * Add tests for accepting any sequence when depythonifying structs and arrays. * Add more tests for objc_support.m to unittest.c * Add tests for OC_PythonArray, OC_PythonDict to unittest.c The first two bullets require at least some GUI tests. Less important items -------------------- Refactor some parts of the bridge ................................. From the top of my head: * Restructure selector.m, this file is too long and complicated. We could do away with the difference between method implemented in Python and ObjC. * Likewise for class-builder.m, this file is way to large. Support for GNUstep ................... The current CVS version contains some support for GNUstep, this needs to be enhanced. Naming convention / coding style ................................ Global symbols should be named with a prefix. We currently use several prefixes and some symbols do not have a prefix at all. See the document `Coding style` for a proposal for a coding style and naming convention. The code should be changed to conform to this document. .. _`Coding style`: coding-style.txt Add templates for various file types .................................... Add Xcode/PB file templates for various types of files, at least for an empty python file. Add templates for various project-types ....................................... We currently have a Project Builder template for a basic PyObjC application. We should simular templates for other usefull projects and most importantly a document-based application. Other possibilies include: * Standalone Service * IBPalette * PreferencePane * Screen Saver * Cocoa Bundle In contrast to a template for a document-based application these last four require additional (Objective-C) code: There needs to be a mechanism to initialize a python interpreter and load the python code in the project when the plugin/bundle is loaded. Furthermore we need to make sure that exactly one interpreter is created, even when more than one Python based plugin/bundle is loaded. NOTE: All these are supported for 'pure python' projects, we just have to find a way to make it easier to maintain PB templates. The currently is too much manual labor involved in updating them. Complete Cocoa wrapping ....................... We do not yet have a 100% coverage of the Cocoa API's. We also need code in the testsuite that checks if the function wrappers are working as expected. Someone needs to check if we correctly export all constants from Cocoa and if the generation script finds all global functions. Simularly for the annotations for input/output arguments. We also don't support all "difficult" methods yet, implementing these is not too hard but it is a lot of work. NSDecimal (the C-type) is not yet supported. We also need more support code for NSDecimalNumber. Pickle support .............. Objective-C objects don't support pickling. They do pickle without errors using protocol version 2 (Python >= 2.3a2), but that doesn't include the state of the Objective-C object only that of the proxy. This is post-1.0 work, in general this is a hard problem because it may involve object cycles that cross the Python-ObjC boundary. NOTE: 1.0b1+ contains a patch that disables pickling even for pickle protocol 2, that's more usefull than writing incomplete objects to the pickle. NSCoder support ............... It might be usefull to add default implementations of ``encodeWithCoder:`` and ``initWithCoder:`` methods to Python subclasses of Objective-C classes that implement these. See also `Pickle support`. Known issues ............ It is impossible to support methods with a variable number of arguments in the generic code (you have to reimplement allmost all of the logic of these methods in order to know how many and which types of arguments are expected). Luckily there are not many varargs methods and most (if no all) of them can be easily avoided. XXX: The paragraph above should be moved to the documentation, it is not a todo item. All existing varargs methods should be located and documented. Where possible we should provide custom wrappers, otherwise we should document alternatives. We should further investigate why the call to ``PyType_Ready(&PyTuple_Type)`` in module.m is necessary. See `bug #77730`__. .. _: http://sourceforge.net/tracker/index.php?func=detail&aid=777308&group_id=14534&atid=114534 Code cleanup ............ * Check all error/exception messages * Check/cleanup error handling * Finish in-code documentation for the C code Cleanup Examples ................ The CurrentConvertor example should be removed, this should be the same as the final step of the tutorial. It isn't at the moment because additional cruft in the example. * addressbook.py Cleanup, maybe transform this into a usefull utility (import/export from/to CSV springs to mind). * autoreadme.py Add documentation * dictionary.py Should be a unittest, and should be added to the (non-existing) manual * pydict-to-objcdict.py Move to unittests * subclassing-objective-c.py Move to documentation (unittest?) * super-call.py Move to documentation (unittest?) Add examples that demonstrate: - how to use a lot of Cocoa features - how to integrate with MacPython Access to method implementations ................................ Add a wrapper for 'instanceMethodForSelector:' and 'methodForSelector:', these should return selector objects that call a specific C function. This would make it possible to use classAddMethods to replace existing methods while still calling the previous implementation. The same mechanism could be used to wrap "simple" global functions. OTOH the current mechanism works good enough at the moment. Performance tuning/testing .......................... Design and implement a set of performance tests for the bridge. Use this to investigate and fix any possible performance problems. Add freelists ............. PyObjCSelector objects and PyObjCObject objects are created on a regular basis, we should check if using freelists would speed this up. See also `Performance tuning/testing`. Key-Value Encoding .................. XXX: Need to check if the current implementation is correct. The takeValue:forKey: implementation correctly emits notifications (on MacOS X 10.3). MacOS X 10.3 is currently detected at compile-time, this should probably be done dynamicly. The right notifications are not yet emitted for: * setattr() on Objective-C objects There is preliminary (sp?) support in objc-object.m, but I'm not sure if this we really should do this at all. * setattr() on pure Python objects It is impossible to detect such changes, even finding the right ObjC wrapper is not possible at the moment (but that is fixable). The documentation should mention that observations don't work for pure Python objects. Scott Anguish mentioned on one of the Cocoa lists that the right way to override the key-value related methods is different from what we're doing. Formal Protocols, Distributed Objects ..................................... ``DO`` seems to use formal protocols, we don't support those at all. Links to Apple documentation ............................ Links to Apple documentation are not stable, can we add a layer of indirection here, e.g. link to the PyObjC website that will redirect to the right location? But: we should also provide links to locally installed documetation, especially in the documentation that will be installed on the users machine. Installer support for OSX 10.3 .............................. XXX: I have an osxpkg module, but that is completely untested. There should be at least two installers: one for Jaguar and one for Panther, they should share as much source-code as possible. Related to this: it would probably be usefull to rewrite buildpkg.py, this module has been hacked up to support new-style packages. It should be rewritten based on the Apple documentation on the layout of packages, there is no need to support 10.1-style packages. This new module should be donated to MacPython). Implement more of NSMutableDictionary in OC_PythonDictionary ............................................................. The implementation of OC_PythonDictionary is very minimal, we should add additional methods in the NSMutableDictionary interface if those can be implemented efficiently. The default implementation will take care of the methods we cannot implement efficiently. And the same is true of OC_PythonArray Finish support for methodForSelector: ------------------------------------- * All call_ functions in Foundation and AppKit should support calling IMP-wrappers. * You should be able to use an IMP as the implementation of a method in a different class. * More unittests Make it possible to redefine classes .................................... For IDE's it would be pretty usefull to be able to redefine classes. It should not be possible to redefine pure ObjC classes, and the redefined class should be in the same module (determined by name). Both are needed to avoid accidental errors (e.g. two modules definining a class with the same name, which is perfectly valid in plain Python). Rewrite packaging scripts ......................... The scripts we use for doing releases should be cleaned up, generic functionality should be made available for others. Rewrite scripts/find-raw-pointers.py .................................... This is a script for finding 'difficult' methods. The script should be refactored to make it easier to create readable reports.