[Pythonmac-SIG] Macintosh modules/Carbon/documentation

[has]

Jack Jansen wrote:

> On  30-Mar-2007, at 22:55 , Kevin Walzer wrote:
>
>> Looking at the "Macintosh Library" documentation that ships with  
>> 2.5, I
>> see a lot of outdated stuff: references to the old PythonIDE,
>> PackageManager, and so on. What is the process for updating these  
>> docs,
>> submitting a bug report, etc.?
>>
>> Also, there appears to be a lot of modules in the "Macintosh
>> Library"--Carbon modules, generally--that are undocumented, or are
>> broken, or (almost as bad) no one know if they work or not. Has  
>> anyone
>> gone through these to sort out what works, what should be deprecated,
>> etc.? Does it make sense to deprecate the entire Carbon module?  
>> What's
>> the process for this?
>
> I had a chat about this with Ronald a few months ago, where we  
> basically went through all the modules. Ronald,
> do you have your notes handy?

We went over this issue last year as well (although nothing got done  
in time for 2.5's release). See the 'fixing the documentation' thread  
from April 2006.


> Carbon itself should be fine.

Well, it does have some technical problems. Most of the extensions  
haven't been adequately tested and debugged, and there are sometimes  
mapping errors in the auto-generated code. Also, having been created  
some time ago, the Carbon extension APIs may not have kept up with  
more recent changes to the system APIs. In addition, it's going to  
need an as-yet undetermined amount of work to support 64-bit Leopard.


> It is indeed undocumented within the Python documentation, but the  
> transformation from the official Apple C documentation is pretty  
> clear (I think).

Yeah, it takes a little getting used to, but it's mostly  
straightforward. The one thing which could be better explained is  
constructors as it's not obvious how to create new instances of  
Carbon types. Type instantiation follows Carbon, not Python, idioms,  
so instead of calling a type's constructor method, e.g. AEDesc(...),  
which doesn't work, you have to call a separate module function, e.g.  
AECreateDesc(...).


My own position remains that the best thing for Python would be to  
junk many of the Mac-specific modules and move the rest, including  
Carbon, into a separate osxall package a-la win32all where it can be  
updated and maintained separately to the main Python framework.  
Easier said than done, of course, but perhaps the 64-bit problem will  
force the issue for 2.6?

Cheers,

has
-- 
http://appscript.sourceforge.net
http://rb-appscript.rubyforge.org
http://appscript.sourceforge.net/objc-appscript.html