Source

pyobjc / pyobjc / Doc / TODO

Full commit
Ronald Oussoren 49e4277 


Ronald Oussoren 35b2052 
Ronald Oussoren 49e4277 
Ronald Oussoren 35b2052 
Ronald Oussoren 49e4277 

Ronald Oussoren 35b2052 
Ronald Oussoren 49e4277 
Ronald Oussoren 35b2052 
Ronald Oussoren 275401b 








Ronald Oussoren 49e4277 

Ronald Oussoren 35b2052 
Ronald Oussoren 49e4277 

Ronald Oussoren 35b2052 
Ronald Oussoren 49e4277 

Ronald Oussoren 35b2052 
Ronald Oussoren 49e4277 

Ronald Oussoren 35b2052 
Ronald Oussoren 2faf415 




Ronald Oussoren 49e4277 

Ronald Oussoren 35b2052 
Ronald Oussoren 86504dc 


Ronald Oussoren 49e4277 





Ronald Oussoren 86504dc 


Ronald Oussoren 07ff22c 
Ronald Oussoren 86504dc 
Ronald Oussoren 07ff22c 
Ronald Oussoren 65074c8 

Ronald Oussoren 0702749 
Ronald Oussoren ce4d2de 


Ronald Oussoren 65074c8 






Ronald Oussoren 0702749 

Ronald Oussoren 49e4277 
Ronald Oussoren b90dea6 
Ronald Oussoren 49e4277 


Ronald Oussoren 120e0dd 




Ronald Oussoren 944730f 


Ronald Oussoren 4de777c 

Ronald Oussoren 49e4277 


Ronald Oussoren 65074c8 

Ronald Oussoren 49e4277 











Ronald Oussoren 83b7a85 





Ronald Oussoren 7491441 

Ronald Oussoren 49e4277 




Ronald Oussoren 83b7a85 
Ronald Oussoren 49e4277 
Ronald Oussoren 642feab 
Ronald Oussoren 49e4277 
Ronald Oussoren 642feab 
Ronald Oussoren 49e4277 
Ronald Oussoren 642feab 
Ronald Oussoren 49e4277 
Ronald Oussoren 642feab 
Ronald Oussoren 49e4277 
Ronald Oussoren 642feab 
Ronald Oussoren 49e4277 








Ronald Oussoren 79329e1 



Ronald Oussoren 49e4277 






Ronald Oussoren 944730f 

Ronald Oussoren 49e4277 
Ronald Oussoren d203c36 


Ronald Oussoren c638c31 

Ronald Oussoren 2d58917 
Ronald Oussoren 63e0faa 






Ronald Oussoren d203c36 


Ronald Oussoren 0af4f90 


Ronald Oussoren 63e0faa 





Ronald Oussoren fc7de0c 
Ronald Oussoren d203c36 

Ronald Oussoren fc7de0c 








Ronald Oussoren 0af4f90 


Ronald Oussoren 944730f 


Ronald Oussoren d2b6d0b 




Ronald Oussoren 6f1f311 








Ronald Oussoren 0af4f90 
Ronald Oussoren 4c3983c 

Ronald Oussoren fc7de0c 
Ronald Oussoren 4c3983c 


Ronald Oussoren fc7de0c 
Ronald Oussoren 4c3983c 


















Ronald Oussoren 2faf415 





Ronald Oussoren 1316d7c 
Ronald Oussoren 944730f 







Ronald Oussoren 79329e1 


Ronald Oussoren 944730f 



Ronald Oussoren 0af4f90 
Ronald Oussoren 07ff22c 
Ronald Oussoren a21c2a2 


Ronald Oussoren 0af4f90 
Ronald Oussoren 79329e1 

Ronald Oussoren a21c2a2 
Ronald Oussoren 0af4f90 



Ronald Oussoren 86504dc 

Ronald Oussoren c638c31 

















Ronald Oussoren feefa47 
Ronald Oussoren cc8fac9 


Ronald Oussoren feefa47 













Ronald Oussoren 65074c8 



Ronald Oussoren 86504dc 

Ronald Oussoren 65074c8 







Ronald Oussoren d4b5098 









Ronald Oussoren 6f1f311 


























Ronald Oussoren cc8fac9 





=========
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.