[Pythonmac-SIG] Fixing the documentation...

[has]

Russell Finn wrote:

>Well, no; see below.
>
>> join('d1', 'Users')
>> ':d1:Users' # wrong! (should be 'd1:Users')
>
>The docstring for macpath.isabs() contradicts this, however:
>
>    """On the Mac, relative paths begin with a colon,
>    but as a special case, paths with no colons at all are also relative.
>    Anything else is absolute (the string up to the first colon is the
>    volume name)."""
>
>This is in fact the historic interpretation of pathnames under Mac OS
>before OS X

Hmm, missed that. Ta for pointing it out. So that's an official HFS thing, rather than just a macpath thing, I take it? Somewhat strange anyway.

--

Ronald Oussoren wrote:

>>>More examples of brokenness:
>>>
>>>exists('d1:Users:has')
>>>False
>>>exists('/Users/has')
>>>True
>>
>>[snip]
>>
>>If d1 is the name of your system volume, then that would be a bug --

Yep, it's a valid HFS path. Ergo, bug.


>Right. Any function that touches the actual filesystem won't work

So those should be deprecated/removed/flagged as not supporting HFS paths, and therefore no longer a useful or relevant part of the module.


>>I don't believe it's "broken", but I won't claim it
>>does much that's useful in the modern world other than handle
>>HFS-style paths (if you happen to have one for some reason).
>
>Which happens with some Carbon related APIs and appeantly also some scripting interfaces.

I dunno how many Carbon APIs require HFS path strings, as opposed to FSRefs, etc. (which the Python wrappers already allow you to convert to/from POSIX paths). OS 9 was pretty thorough in using file objects rather than path strings. So I'm a bit dubious this is such a big deal.

As for scriptable applications that require HFS, not POSIX, paths, the problem here is that there's no easy way to convert POSIX path strings to HFS path strings and back using Python. macpath is zero relevance/use here since it doesn't provide functions for this, so this is no justification for keeping it.


>Those functions exists and are part of the normal Carbon API's. macpath is an implementation for the path manipulation APIs in os.path for when you want to manipulate OS9 style paths. That is *all* it can be used for unless you're running on OS9.

So the ONLY thing it's still good for is path munging then. Which isn't such a good idea to do since HFS path strings are fundamentally unsafe anyway - they can't distinguish between identically named volumes. As I say earlier, you're better off converting paths to POSIX form for splitting and joining them.

If you really want to keep it, you need to stub/remove everything except the functions that still apply to HFS paths, which by my guess is: commonprefix, join, normcase, normpath, split, splitext.

Still, it's a pretty pathetic collection of weak and obsolete functions with hardly any uses or users, and I honestly can't see any good reason why it needs to stay an active part of the standard library. Smacks of "Never mind the quality; feel the width." So I still say deprecate, but if not then it should at least be cleaned up so the complete garbage is removed.

HTH

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