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

Ron Adam rrr at ronadam.com
Tue Sep 5 20:35:40 CEST 2006

Michael Chermside wrote:

Jim Jewett writes:

This change [in docs] looks wrong:

PyDocSTRVAR(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)

This isn't immediately clear to me what I will get.

  s.partition(sep) -> (left, sep, right)
  s.rpartition(sep) -> (left, sep, right)

Would be clearer, along with an explanation of what left, and right are.

I hope this discussion is only about the words used and the documentation and not about the actual order of what is received. I would expect both the following should be true, and it is the current behavior.

 ''.join(s.partition(sep)) -> s
 ''.join(s.rpartition(sep)) -> s

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

Maybe this?

partition(...) S.partition(sep) -> (left, sep, right)

 Partition a string at the first occurrence of sep from the
 left into a tuple of left, sep, and right parts.

 Returns (S, '', '') if sep is not found in S.

rpartition(...) S.rpartition(sep) -> (left, sep, right)

 Partition a string at the first occurrence of sep from the right
 into a tuple of left, sep, and right parts.

 Returns ('', '', S) if sep is not found in S.

I feel the terms head and tail, rest etc... should be used in examples where their meaning will be clear by the context they are used in. But not in the definition where their meanings are not obvious.

Cheers, Ron

More information about the Python-Dev mailing list