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.

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)
    

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.

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