[Python-Dev] Fwd: Problem withthe API for str.rpartition()

[Michael Chermside]

Jim Jewett writes:
> This change [in docs] looks wrong:
>
> PyDoc_STRVAR(rpartition__doc__,
> -"S.rpartition(sep) -> (head, sep, tail)\n\
> +"S.rpartition(sep) -> (tail, sep, head)\n\

Raymond Hettinger replies:
> It is correct.  There may be some confusion in terminology.  Head  
> and tail do not mean left-side or right-side. Instead, they refer to  
> the "small part chopped-off" and "the rest that is still choppable".  
> Think of head and tail in the sense of car and cdr.


It is incorrect. The purpose of documentation is to explain
things to users, and documentation which fails to achieve this
is not "correct". The level of confusion generated by using "head"
to refer to the last part of the string and "tail" to refer to
the beginning, is quite significant.

How about something like this:

    S.partition(sep) -> (head, sep, tail)
    S.rpartition(sep) -> (tail, sep, rest)

Perhaps someone else can find something clearer than my suggestion,
but in my own head, the terms "head" and "tail" are tighly bound
with the idea of beginning and end (respectively) rather than with
the idea of "small part chopped off" and "big part that is still
choppable".

-- Michael Chermside