Scripting Clinic: Curl Up With Python - Page 2

 By Carla Schroder
Page 2 of 2   |  Back to Page 1
Print Article
Continued From Page 1

Doc Strings
Python has a built-in documentation tool called "doc string." These are designed to be used by automatic indexing tools, for creating help docs. Doc strings belong to functions, classes, methods, and methods. They immediately follow the header, and are indented, like this:

>>> def lamerFunction():
...        """This is a one-line comment."""

Comments can be as long as needed:

>>> def wicked_kewl_function():
...        """This is a multiline doc string.
...       See, here's the second line.
...       """

This also illustrates Python's two prompts. >>> marks the beginning of a new command. ... is the sub-prompt, which marks all the lines in a command. You have to enter a blank line to get back to the main prompt.

You can read doc strings in the Python interpreter, to find out what a function is for. Note that doc is enclosed by double underlines:

>>> print lamerFunction.__doc__
This is a one-line comment.

>>> print wicked_kewl_function.__doc__
This is a multiline doc string.

      See, here's the second line.

Or, use Python's built-in help:

>>> help(wicked_kewl_function)

Help on function wicked_kewl_function in module __main__:

This is a multiline doc string.

       See, here's the second line.

Hit Q to get out of the help window. So you see, writing detailed, helpful doc strings goes a long ways towards keeping your Python scripts and program understandable, and maintainable.

Python also supports ordinary comments:

# this script written by Awesome Geekasaurus
# for sorting my eleventy-nine zillion pizza recipes

Like any other *nix program, Python has a voracious hunger for over-interpreting strings, which makes using literal strings a real pain in the patootie. How I wish for a simple method to enclose a string containing all kind of quotation marks, forward slashes, backslashes, semi-colons, and everything I want, without having to escape individual characters. My fave is escaping the escape character: \\

OK, whining aside, we're stuck with what we have. Python's method of escaping quotes is just as odd as anyone else's:

>>> 'This is an "example" of using single and "double" quotes in Python.'
'This is an "example" of using single and "double" quotes in Python.'

That's not so bad, is it. Well, remember Bizarro World in the old Superman comics? The planet of people who did everything backwards? I think that's where Python's quoting conventions came from. Sometimes single quotes get turned to double quotes:

>>> 'This is an \'example\' of using single and \'double\' quotes in Python.'
"This is an 'example' of using single and 'double' quotes in Python."

To really have a good time, mix apostrophes and quotes:

>>> 'Let\'s go "nuts" with apostrophes, "quotes", and stuff!'
'Let\'s go "nuts" with apostrophes, "quotes", and stuff!'

Ew, that looks bad. But when you assign the string to a variable and print it, it all comes out right:

>>>speech='Let\'s go "nuts" with apostrophes, "quotes", and stuff!'
>>> print speech
Let's go "nuts" with apostrophes, "quotes", and stuff!

One way to get completely literal strings is with the print command, and triple quotes, like in doc strings:

>>> print """'We have "quote's "single" and 'double' '' and weird "' s'tuff'''"""
'We have "quote's "single" and 'double' '' and weird "' s'tuff'''

How is this useful? Take a look at this if statement:

>>> num = int(raw_input("Please enter an integer: "))
Please enter an integer: -15
>>> if num < 0:
...       print """num is less than zero, and I
...       can use 'quote's" anyway I want
...       'inside' the "triple quotes'
...       """
... else:
...       print """'Eh, it's greater than zero'.
...       '"""
num is less than zero, and I
      can use 'quote's" anyway I want
      'inside' the "triple quotes'

This is not as convenient, perhaps, as having a nice variable to plug in whenever you want to print that particular comment. But it gets the job done.

Next time on Scripting Clinic we'll put together a real live script, and dissect it line-by-line, so you'll understand what the Python bits do, and what role other Linux commands play. Let me know if there's a particular task you'd like to see scripted, preferably something a little more fun than Yet Another Backup Script.

Python is very well-documented, roll on over to python.org and start reading.

This article was originally published on Apr 30, 2004
Get the Latest Scoop with Networking Update Newsletter