I stumbled upon this by chance. Is the following behaviour by design?

>>> s = 'a\tb'
>>> s.expandtabs(1) == s.expandtabs(2)
True

In fact:
>>> s.expandtabs(1)
'a b' # 1 space
>>> s.expandtabs(2)
'a b' # 1 space
>>> s.expandtabs(3)
'a  b' # 2 spaces
>>> s.expandtabs(4)
'a   b' # 3 spaces

It seems to be an off-by-one difference from 2 onwards. 

Tested with python versions 2.7.4, 3.2.4 and 3.3.1 on a Linux x86_64 machine.

Yes, the behavior is by design.  I think you are misunderstanding how exandtabs() works.  The "tabsize" argument indicates the number of columns each tab position occupies.  So, with a tabsize of 4, the tab positions occur every four columns; the tab positions are where the characters immediately following the tab character start.  Perhaps this example will make the behavior clearer:

>>> '1\t2'.expandtabs(4)
'1   2'
>>> '12\t3'.expandtabs(4)
'12  3'
>>> '123\t4'.expandtabs(4)
'123 4'

It does, thank you. Maybe hat example could be added to the docuentation?

That's a good point.  Here's a patch for the documentation with a simplified example:

      >>> '01\t456\t89'.expandtabs(4)
      '01  456 89'

What do others think: is an example useful and, if so, this example?

LGTM.

I agree the doc could be clearer and Ned's example is very good. However I'd go one step forward and add a further elaboration of how the method works. This is the current doc (in default branch):

  Return a copy of the string where all tab characters are replaced by zero or more spaces, depending on the current column and the given tab size. The column number is reset to zero after each newline occurring in the string. If tabsize is not given, a tab size of 8 characters is assumed. This doesn’t understand other non-printing characters or escape sequences.

I'd say this (note new second sentence):

  Return a copy of the string where all tab characters are replaced by zero or more spaces, depending on the current column and the given tab size. Every time a \t char appears in the string, the text before it gets padded with spaces until the next tab position is reached. The column number is reset to zero after each newline occurring in the string. If tabsize is not given, a tab size of 8 characters is assumed. This doesn’t understand other non-printing characters or escape sequences.

And then follow with Ned's example.

"This doesn’t understand other non-printing characters or escape sequences."

This might also be improved.  Does it mean that all characters are considered having len(c) == 1, even if they are not printable or escape sequence (and which escape sequences? \f, \v?)?

Adding an example with tabsize=8 might also help, but it might not be necessary if the wording is improved as Eli suggested.

Thanks for the suggested.  Here's a revised wording and a slightly more legible example:


   Return a copy of the string where all tab characters are replaced by zero or
   more spaces, depending on the current tab column and the given tab size.
   Starting at the first character of the string, the tab column is set to
   zero.  Whenever a tab character (``\t``) is encountered, space characters
   are inserted as needed until the next tab position is reached and the tab
   column is set to that tab position; the tab character itself is not copied.
   Whenever a newline character (``\n`` or ``\r``) is encountered, it is copied
   and the tab column is reset to zero.  Any other character is copied unchanged
   and the tab column is incremented by one regardless of how it may be
   represented when printed.  If *tabsize* is not given, a tab size of 8
   characters is assumed.

      >>> '012\t4\t89'.expandtabs(4)
      '012 4   89'

It's better, although the distinction between "tab column" and "tab position" is not entirely clear.

Another round based on comments.  I also just noticed that the current doc incorrectly claims that tabs are replaced by *zero* or more spaces.


   Return a copy of the string where all tab characters are replaced by one or
   more spaces, depending on the current column and the given tab size.  Tab
   positions occur every *tabsize* characters (default is 8, giving tab
   positions at columns 0, 8, 16 and so on).  To expand the string, the current
   column is set to zero and the string is examined character by character.  If
   the character is a tab (``\t``), one or more space characters are inserted
   in the result until the current column is equal to the next tab position.
   (The tab character itself is not copied.)  If the character is a newline
   (``\n``) or return (``\r``), it is copied and the current column is reset to
   zero.  Any other character is copied unchanged and the current column is
   incremented by one regardless of how the character is represented when
   printed.

      >>> '01\t012\t0123\t01234'.expandtabs()
      '01      012     0123    01234'
      >>> '01\t012\t0123\t01234'.expandtabs(4)
      '01  012 0123    01234'

LGTM!

New changeset 6a02d2af814f by Ned Deily in branch '2.7':
Issue #17670: Provide an example of expandtabs() usage.
http://hg.python.org/cpython/rev/6a02d2af814f

New changeset 5b6ccab52a4d by Ned Deily in branch '3.3':
Issue #17670: Provide an example of expandtabs() usage.
http://hg.python.org/cpython/rev/5b6ccab52a4d

New changeset 1a6cb6d8591a by Ned Deily in branch 'default':
Issue #17670: merge from 3.3
http://hg.python.org/cpython/rev/1a6cb6d8591a