7.4: The Help Function

Learning Objectives

By the end of this section you should be able to

• Use the help() function to explore a module's contents.
• Identify portions of code included in the documentation.

Colors on websites

This section introduces an example module for working with HTML colors. HyperText Markup Language (HTML) is used to design websites and graphical applications. Web browsers like Chrome and Safari read HTML and display the corresponding contents. Ex: The HTML code <p style="color: Red">Look out!</p> represents a paragraph with red text.

HTML defines 140 standard color names. Additional colors can be specified using a hexadecimal format: #RRGGBB. The digits RR, GG, and BB represent the red, green, and blue components of the color. Ex: #DC143C is 220 red + 20 green + 60 blue, which is the color Crimson.

Red, green, and blue values range from 0 to 255 (or 00 to FF in hexadecimal). Lower values specify darker colors, and higher values specify lighter colors. Ex: #008000 is the color Green, and #00FF00 is the color Lime.

Checkpoint: HTML color codes

Concepts in Practice \(\PageIndex{1}\): HTML color codes

What color is #000080?

1. maroon red
2. navy blue
3. olive green

Answer

b. The digits have 0 red and 0 green, so the color must be a shade of blue. Navy is a darker version of standard blue, #0000FF .

Concepts in Practice \(\PageIndex{2}\): HTML color codes

What is 255 in hexadecimal?

1. 00
2. 80
3. FF

Answer

c. FF in hexadecimal is 255, the maximum amount of red, green, or blue in a color.

Concepts in Practice \(\PageIndex{3}\): HTML color codes

Which color is lighter?

1. #FFA500 (orange)
2. #008000 (green)

Answer

a. The red, green, and blue values for orange are higher than the red, green, and blue values for green.

Example colors module

A module for working with HTML color codes would be helpful to graphic designers and web developers. The following Python code is in a file named colors.py.

• Line 1 is the docstring for the module.
• Lines 3–16 assign variables for frequently used colors.
• Lines 18–24 define a function to be used within the module.
• Lines 26–45 define functions to be used in other modules.

Note: The tohex() and torgb() functions use Python features (string formatting and slicing) described later in the book. For now, the documentation and comments are more important than the implementation details.

    """Functions for working with color names and hex/rgb values."""

    # Primary colors
    RED = "#FF0000"
    YELLOW = "#FFFF00"
    BLUE = "#0000FF"

    # Secondary colors
    ORANGE = "#FFA500"
    GREEN = "#008000"
    VIOLET = "#EE82EE"

    # Neutral colors
    BLACK = "#000000"
    GRAY = "#808080"
    WHITE = "#FFFFFF"

    def _tohex(value):
      """Converts an integer to an 8-bit (2-digit) hexadecimal string."""
      if value <= 0:
        return "00"
      if value >= 255:
        return "FF"
      return format(value, "02X")

    def tohex(r, g, b):
      """Formats red, green, and blue integers as a color in hexadecimal."""
      return "#" + _tohex(r) + _tohex(g) + _tohex(b)

    def torgb(color):
      """Converts a color in hexadecimal to red, green, and blue integers."""
      r = int(color[1:3], 16) # First 2 digits
      g = int(color[3:5], 16) # Middle 2 digits
      b = int(color[5:7], 16) # Last 2 digits
      return r, g, b

    def lighten(color):
      """Increases the red, green, and blue values of a color by 32 each."""
      r, g, b = torgb(color)
      return tohex(r+32, g+32, b+32)

    def darken(color):
      """Decreases the red, green, and blue values of a color by 32 each."""
      r, g, b = torgb(color)
      return tohex(r-32, g-32, b-32)

Concepts in Practice \(\PageIndex{4}\): The colors module

What are the components of the color YELLOW?

1. red=0, green=255, blue=255
2. red=255, green=255, blue=0
3. red=255, green=0, blue=255

Answer

b. The hexadecimal for YELLOW is #FFFF00 , meaning 255 red + 255 green + 0 blue.

Concepts in Practice \(\PageIndex{5}\): The colors module

What code would return a darker shade of blue?

1. darken(BLUE)
2. colors.darken(BLUE)
3. colors.darken(colors.BLUE)

Answer

c. Both the darken function and the BLUE variable must be accessed via the colors variable.

Concepts in Practice \(\PageIndex{6}\): The colors module

What symbol indicates that a function is not intended to be called by other modules?

1. underscore (_)
2. number sign (#)
3. colon (:)

Answer

a. Function names that begin with an underscore are intended to be used only within the current module.

Module documentation

The built-in help() function provides a summary of a module's functions and data. Calling help(module_name) in a shell is a convenient way to learn about a module.

Example 7.2: Output of help(colors) in a shell

The documentation below is automatically generated from the docstrings in colors.py.

help(colors)

    Help on module colors:

    NAME
      colors - Functions for working with color names and hex/rgb values.

    FUNCTIONS
      darken(color)
        Decreases the red, green, and blue values of a color by 32 each.

      lighten(color)
        Increases the red, green, and blue values of a color by 32 each.

      tohex(r, g, b)
        Formats red, green, and blue integers as a color in hexadecimal.

      torgb(color)
        Converts a color in hexadecimal to red, green, and blue integers.

    DATA
      BLACK = '#000000'
      BLUE = '#0000FF'
      GRAY = '#808080'
      GREEN = '#008000'
      ORANGE = '#FFA500'
      RED = '#FF0000'
      VIOLET = '#EE82EE'
      WHITE = '#FFFFFF'
      YELLOW = '#FFFF00'

    FILE
      /home/student/Desktop/colors.py
    >>> help(colors)

    Help on module colors:

    NAME
      colors - Functions for working with color names and hex/rgb values.

    FUNCTIONS
      darken(color)
        Decreases the red, green, and blue values of a color by 32 each.

      lighten(color)
        Increases the red, green, and blue values of a color by 32 each.

      tohex(r, g, b)
        Formats red, green, and blue integers as a color in hexadecimal.

      torgb(color)
        Converts a color in hexadecimal to red, green, and blue integers.

    DATA
      BLACK = '#000000'
      BLUE = '#0000FF'
      GRAY = '#808080'
      GREEN = '#008000'
      ORANGE = '#FFA500'
      RED = '#FF0000'
      VIOLET = '#EE82EE'
      WHITE = '#FFFFFF'
      YELLOW = '#FFFF00'

    FILE
      /home/student/Desktop/colors.py

Concepts in Practice \(\PageIndex{7}\): The help() function

The documentation includes comments from the source code.

1. true
2. false

Answer

b. Only docstrings are included in the documentation. All comments are ignored by the help function.

Concepts in Practice \(\PageIndex{8}\): The help() function

In what order are the functions listed in the documentation?

1. alphabetical order
2. definition order
3. random order

Answer

a. The functions are sorted alphabetically by name to make looking up a function easier.

Concepts in Practice \(\PageIndex{9}\): The help() function

Which function defined in colors.py is not included in the documentation?

1. _tohex
2. tohex
3. torgb

Answer

a. Functions that begin with an underscore are intended to be used only within a module, not in other modules.

Try It: Help on modules

The random and statistics modules are useful for running scientific experiments. You can become familiar with these two modules by skimming their documentation.

Open a Python shell on your computer, or use the one at python.org/shell. Type the following lines, one at a time, into the shell.

• import random
• help(random)
• import statistics
• help(statistics)

Many shell environments, including the one on python.org, display the output of help() one page at a time. Use the navigation keys on the keyboard (up/down arrows, page up/down, home/end) to read the documentation. When you are finished reading, press the Q key ("quit") to return to the Python shell.

Try It: Help on functions

The help() function can be called on specific functions in a module. Open a Python shell on your computer, or use the one at python.org/shell. Type the following lines, one at a time, into the shell.

• import random
• help(random.randint)
• help(random.choice)
• import statistics
• help(statistics.median)
• help(statistics.mode)

Remember to use the navigation keys on the keyboard, and press the Q key ("quit") to return to the Python shell.