[Pythonmac-SIG] Fixing the documentation...

[has]

Ronald wrote:

>>>Macpath deals with OS9/Carbon style paths (Volume:directory:file  
>>>instead of /Volume/directory/file).
>>
>>Don't know where you're seeing this; I've tried a few of the functions and none work with HFS-style paths, only POSIX-style paths.
>
> >>> macpath.join('foo', 'bar')
>':foo:bar'

OK, so that has colons - obviously I managed only to try the ones that didn't. :)

That said, the actual result in the above example is wrong. It should be 'foo:bar', since 'foo' is an absolute path (a leading colon indicates a relative path, which is not the same):

join('d1', 'Users')
':d1:Users' # wrong! (should be 'd1:Users')

So that's pretty useless.

More examples of brokenness:

exists('d1:Users:has')
False
exists('/Users/has')
True

isdir('d1:Users:has')
0
isdir('/Users/has')
True

getsize('/Users/has/test.rb')
150
getsize('d1:Users:has:test.rb')
OSError: [Errno 2] No such file or directory: 'd1:Users:has:test.rb'

All demand a POSIX path, not an HFS path.


So the module is well broken on OS X, and has been for the last five years and nobody's said or done anything about it yet. And even fixed it's still semi-worthless since there's a whole bunch of things you still can't do with HFS paths - i.e. no comparable 'os' module for creating, moving, deleting, etc. - and there's nothing in it for converting paths between HFS and POSIX formats so interoperability is also crap. This says it's a fairly useless module in reality, and won't be missed if it's jettisoned now.

What'd make a lot more sense is fixing Carbon.CF so it can be used to convert between the different path formats. This functionality is needed anyway, and it'll allow folk who do need to handle HFS paths to use the os/os.path modules by turning them to POSIX paths and back.


Tell you what: if you really don't want to deprecate it in 2.5, put a warning note on it saying it's multiply broken. If someone cares they can submit patches and it can be fixed in 2.6. If not, it can be deprecated then.

-------
Daniel Lord wrote:

>>>>       2.1 macpath -- MacOS path manipulation functions
>>[...]
>>As I mentioned in another message this module might be useful to work 
>>with OS9-style paths as used by some Carbon API's.
>
>Good suggestion, Ronald. I was just tinkering around with appscript and MS Excel a few days ago (still cannot access some things like borders properly and others are just 'bass-ackwards' in the Excel terminology defs so I gave up) but Excel expects colon-separated paths in file paths (yes even in 2004 when they last updated it).

As for working with HFS paths (and a pox on scriptable apps that require them, btw, because they're fundamentally unreliable), you ought to be able to use Carbon.CF to translate between POSIX/Windows/HFS path styles. Unfortunately, I suspect getting in and out of there may be one of the areas that's broken.

I wouldn't mind adding a makewithhfspath class method and hfspath instance method to macfile's Alias and File classes, but I'd want to be sure I had a correct implementation first, however, as it's not quite as trivial as it sounds on the surface (e.g. volume names are not a direct translation in either direction).

has
-- 
http://freespace.virgin.net/hamish.sanderson/