Few things

[Nick Coghlan]

bearophile wrote:
> I think a better syntax for such multiline strings can be something
> like: remove from all the beginnings of the lines successive to the
> first one a number of spaces equal to the position of ''' in the
> soucecode.

Indeed, a similar rule is used by docstring parsing tools (e.g. the builtin 
help() function). The raw text is kept around, but the display tools clean it up 
according to whatever algorithm best suits their needs.

 >>> def foo():
...     '''This is just a
...        silly text'''
...
 >>> print foo.__doc__
This is just a
        silly text
 >>> help(foo)
Help on function foo in module __main__:

foo()
     This is just a
     silly text

Raw docstrings are rarely what you want to be looking at. The best place for 
info on recommended docstring formats is:
   http://www.python.org/peps/pep-0257.html

If you absolutely, positively need the raw docstrings to be nicely formatted, 
then line continuations can help you out:

 >>> def bar():
...   "This is actually "\
...   "all one line\n"\
...   "but this is a second line"
...
 >>> print bar.__doc__
This is actually all one line
but this is a second line

I'd advise against actually doing this, though - it's non-standard, handling the 
whitespace manually is a serious pain, and most docstring parsers clean up the 
indentation of the conventional form automatically.

Cheers,
Nick.