Source

pyobjc / Doc / TODO

The branch 'pyobjc-ancient' does not exist.
=========
Todo list
=========

.. contents:

Introduction
------------

This document contains an (incomplete) list of work items. 

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

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

Drop support for Python 2.2
...........................

None of the core developers uses Python 2.2 anymore, which means Python 2.2
suffers from bitrot. Furthermore, Python 2.2 on Jaguar is not very useful in
the first place.

Removing Python 2.2 support allows for slightly cleaner code.

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.

* We've several types that wrap pointer values, such as ``SessionWrapper`` in
  ``Modules/AppKit``. Should add a function for creating these types, 
  possibly exposed to C code.

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

Interface Builder Palettes
..........................

IB doesn't "see" PyObjC class definitions. We need to investigate why this
is so.

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

``-copy``
.........

There are issues with implementing ``-copy`` in python, these need to be fixed.

Specifically, overriding an existing ``-copy`` implementation does not work 
unless ``__slots__ == ()``

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

* SessionWrapper (in ``Modules/AppKit``) is one of several types that wrap 
  a single pointer, create a function to build such types (simular to
  ``Modules/objc/struct-wrapper.m``)

* Add a 'test' action to setup.py (e.g. 'python setup.py test'), and
  remove runPyObjCTests.

* Use the ``CArray`` API whenever appropriate.

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

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. 

XXX: We do support accessing protocols (e.g. an equivalent to @protocol(Foo)),
but you cannot define new protocols in python yet.

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

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.
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.