Docstrings, help, and dir

As part of the Function Design Recipe, we've been writing descriptions of our functions and placing them below the function header inside triple-quoted strings. These descriptions are called docstrings, which stands for documentation strings.

The docstrings are useful to others reading our saved programs and using our code, and these descriptions can be accessed using Python's built-in function help.

Recall our function square, from earlier:

In [6]:
def square(num):
    """(number) -> number
    
    Return num squared.
    
    >>> square(5)
    25
    >>> square(-6)
    36
    """
    return num * num

In the Python shell, we can called help(square) to get the docstring description:

In [7]:
help(square)

Help on function square in module __main__:

square(num)
    (number) -> number
    
    Return num squared.
    
    >>> square(5)
    25
    >>> square(-6)
    36

We can use help and another built-in function named dir to find out more about Python's built-in functions too. Calling dir(__builtins__) produces output that includes a list of Python's built-in functions (for now, focus only on the names that are entirely lowercase):

In [8]:
dir(__builtins__)
Out[8]:
['ArithmeticError',
 'AssertionError',
 'AttributeError',
 'BaseException',
 'BlockingIOError',
 'BrokenPipeError',
 'BufferError',
 'BytesWarning',
 'ChildProcessError',
 'ConnectionAbortedError',
 'ConnectionError',
 'ConnectionRefusedError',
 'ConnectionResetError',
 'DeprecationWarning',
 'EOFError',
 'Ellipsis',
 'EnvironmentError',
 'Exception',
 'False',
 'FileExistsError',
 'FileNotFoundError',
 'FloatingPointError',
 'FutureWarning',
 'GeneratorExit',
 'IOError',
 'ImportError',
 'ImportWarning',
 'IndentationError',
 'IndexError',
 'InterruptedError',
 'IsADirectoryError',
 'KeyError',
 'KeyboardInterrupt',
 'LookupError',
 'MemoryError',
 'NameError',
 'None',
 'NotADirectoryError',
 'NotImplemented',
 'NotImplementedError',
 'OSError',
 'OverflowError',
 'PendingDeprecationWarning',
 'PermissionError',
 'ProcessLookupError',
 'ReferenceError',
 'ResourceWarning',
 'RuntimeError',
 'RuntimeWarning',
 'StopIteration',
 'SyntaxError',
 'SyntaxWarning',
 'SystemError',
 'SystemExit',
 'TabError',
 'TimeoutError',
 'True',
 'TypeError',
 'UnboundLocalError',
 'UnicodeDecodeError',
 'UnicodeEncodeError',
 'UnicodeError',
 'UnicodeTranslateError',
 'UnicodeWarning',
 'UserWarning',
 'ValueError',
 'Warning',
 'ZeroDivisionError',
 '__IPYTHON__',
 '__IPYTHON__active',
 '__build_class__',
 '__debug__',
 '__doc__',
 '__import__',
 '__loader__',
 '__name__',
 '__package__',
 '__spec__',
 'abs',
 'all',
 'any',
 'ascii',
 'bin',
 'bool',
 'bytearray',
 'bytes',
 'callable',
 'chr',
 'classmethod',
 'compile',
 'complex',
 'copyright',
 'credits',
 'delattr',
 'dict',
 'dir',
 'divmod',
 'dreload',
 'enumerate',
 'eval',
 'exec',
 'filter',
 'float',
 'format',
 'frozenset',
 'get_ipython',
 'getattr',
 'globals',
 'hasattr',
 'hash',
 'help',
 'hex',
 'id',
 'input',
 'int',
 'isinstance',
 'issubclass',
 'iter',
 'len',
 'license',
 'list',
 'locals',
 'map',
 'max',
 'memoryview',
 'min',
 'next',
 'object',
 'oct',
 'open',
 'ord',
 'pow',
 'print',
 'property',
 'range',
 'repr',
 'reversed',
 'round',
 'set',
 'setattr',
 'slice',
 'sorted',
 'staticmethod',
 'str',
 'sum',
 'super',
 'tuple',
 'type',
 'vars',
 'zip']

Once we've found a function using dir, we can find out more about it by calling help:

In [9]:
help(abs)

Help on built-in function abs in module builtins:

abs(...)
    abs(number) -> number
    
    Return the absolute value of the argument.
In [10]:
help(round)

Help on built-in function round in module builtins:

round(...)
    round(number[, ndigits]) -> number
    
    Round a number to a given precision in decimal digits (default 0 digits).
    This returns an int when called with one argument, otherwise the
    same type as the number. ndigits may be negative.

Practice Exercise: learning about functions using help

Consider this description of built-in function ord:

In [11]:
help(ord)

Help on built-in function ord in module builtins:

ord(...)
    ord(c) -> integer
    
    Return the integer ordinal of a one-character string.
  1. How many parameter(s) does function ord have?
  2. What are the type(s) of ord's parameter(s)?
  3. Give an example of how to call on function ord.