5.7. Help and doc strings

There are a number of basic Python and IPython help facilities, which can help you learn more about Python objects and functions.

5.7.1. Basic Python help

Start with the help function:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
 >>> help(list)
Help on class list in module __builtin__:

class list(object)
 |  list() -> new empty list
 |  list(iterable) -> new list initialized from iterable's items
 |
 |  Methods defined here:
 |
 |  __add__(...)
 |      x.__add__(y) <==> x+y
 |
 |  __contains__(...)
 |      x.__contains__(y) <==> y in x
 |
 |  __delitem__(...)
 |      x.__delitem__(y) <==> del x[y]
 |
 |  __delslice__(...)
 |      x.__delslice__(i, j) <==> del x[i:j]
 |
 |      Use of negative indices is not supported.
 |
 |  __eq__(...)
|      x.__eq__(y) <==> x==y
 |
 |  __ge__(...)
 |      x.__ge__(y) <==> x>=y
 |
 |  __getattribute__(...)
 |      x.__getattribute__('name') <==> x.name
 |
 |  __getitem__(...)
 |      x.__getitem__(y) <==> x[y]
 |
 |  __getslice__(...)
 |      x.__getslice__(i, j) <==> x[i:j]
 |
 |      Use of negative indices is not supported.
 |
 |  __gt__(...)
 |      x.__gt__(y) <==> x>y
 |
 |  __iadd__(...)
 |      x.__iadd__(y) <==> x+=y
 |
 |  __imul__(...)
    ...

This particular help string has a lot more information, more omitted here.

Most Python builtin functions have documentation strings stored on an attribute __doc__, so you can read doc strings like this:

1
2
3
4
5
>>> print len.__doc__

len(object) -> integer

Return the number of items of a sequence or mapping.

The same is true of modules. Once a module is loaded, its documentation string can be printed as above. For example, documentation for the regular expression module, re, which will be extensively covered in the next chaoter, can be accessed as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
>>> import re
>>> print re.__doc__
Support for regular expressions (RE).

This module provides regular expression matching operations similar to
those found in Perl.  It supports both 8-bit and Unicode strings; both
the pattern and the strings being processed can contain null bytes and
characters outside the US ASCII range.

Regular expressions can contain both special and ordinary characters.
Most ordinary characters, like "A", "a", or "0", are the simplest
...

For any module or any class instance, you can learn the set of functions defined in the module or the set of attributes of the class, by using the dir (directory) function. For example, let’s take take an instance of the list type:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
>>> L = ['a']
>>> dir(L)
['__add__', '__class__', '__contains__', '__delattr__', '__delitem__',
  '__delslice__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__',
  '__getitem__', '__getslice__', '__gt__', '__hash__', '__iadd__', '__imul__',
  '__init__', '__iter__', '__le__', '__len__', '__lt__', '__mul__', '__ne__',
  '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__reversed__', '__rmul__',
  '__setattr__', '__setitem__', '__setslice__', '__sizeof__', '__str__',
  '__subclasshook__', 'append', 'count', 'extend', 'index', 'insert', 'pop',
  'remove', 'reverse', 'sort']

Thus we get at the same set of methods listed by the help function, but without the documentation, sometimes an easier way to get at the information when you know what you’re looking for.

Python’s online documentation is extensive, and is usually the first thing listed in the Google search results for some Python function or module accompanied by the word Python.

5.7.2. Basic IPython help

IPython provides an extended help, using the question mark operator. See how to use the question mark operator, as well other IPython help facilities, see the IPython docs.

In addition, when you are typing a function and its arguments in the IPython console or a notebook, if you pause after you type the left parentheses, a small help window appears with function documentation, if available.

../_images/IPython_function_help.png