Search

Text Color

Margin Size

Font Type

Enable Dyslexic Font

7.4: The Help Function

Last updated

Mar 30, 2025
Save as PDF
- 7.3: Top-level Code
- 7.5: Finding Modules

$\newcommand{\vecs}[1]{\overset { \scriptstyle \rightharpoonup} {\mathbf{#1}} }$

$\newcommand{\vecd}[1]{\overset{-\!-\!\rightharpoonup}{\vphantom{a}\smash {#1}}}$

$\newcommand{\id}{\mathrm{id}}$ $\newcommand{\Span}{\mathrm{span}}$

( \newcommand{\kernel}{\mathrm{null}\,}\) $\newcommand{\range}{\mathrm{range}\,}$

$\newcommand{\RealPart}{\mathrm{Re}}$ $\newcommand{\ImaginaryPart}{\mathrm{Im}}$

$\newcommand{\Argument}{\mathrm{Arg}}$ $\newcommand{\norm}[1]{\| #1 \|}$

$\newcommand{\inner}[2]{\langle #1, #2 \rangle}$

$\newcommand{\Span}{\mathrm{span}}$

$\newcommand{\id}{\mathrm{id}}$

$\newcommand{\Span}{\mathrm{span}}$

$\newcommand{\kernel}{\mathrm{null}\,}$

$\newcommand{\range}{\mathrm{range}\,}$

$\newcommand{\RealPart}{\mathrm{Re}}$

$\newcommand{\ImaginaryPart}{\mathrm{Im}}$

$\newcommand{\Argument}{\mathrm{Arg}}$

$\newcommand{\norm}[1]{\| #1 \|}$

$\newcommand{\inner}[2]{\langle #1, #2 \rangle}$

$\newcommand{\Span}{\mathrm{span}}$ $\newcommand{\AA}{\unicode[.8,0]{x212B}}$

$\newcommand{\vectorA}[1]{\vec{#1}} % arrow$

$\newcommand{\vectorAt}[1]{\vec{\text{#1}}} % arrow$

$\newcommand{\vectorB}[1]{\overset { \scriptstyle \rightharpoonup} {\mathbf{#1}} }$

$\newcommand{\vectorC}[1]{\textbf{#1}}$

$\newcommand{\vectorD}[1]{\overrightarrow{#1}}$

$\newcommand{\vectorDt}[1]{\overrightarrow{\text{#1}}}$

$\newcommand{\vectE}[1]{\overset{-\!-\!\rightharpoonup}{\vphantom{a}\smash{\mathbf {#1}}}}$

$\newcommand{\vecs}[1]{\overset { \scriptstyle \rightharpoonup} {\mathbf{#1}} }$

$\newcommand{\vecd}[1]{\overset{-\!-\!\rightharpoonup}{\vphantom{a}\smash {#1}}}$

$\newcommand{\avec}{\mathbf a}$

$\newcommand{\bvec}{\mathbf b}$

$\newcommand{\cvec}{\mathbf c}$

$\newcommand{\dvec}{\mathbf d}$

$\newcommand{\dtil}{\widetilde{\mathbf d}}$

$\newcommand{\evec}{\mathbf e}$

$\newcommand{\fvec}{\mathbf f}$

$\newcommand{\nvec}{\mathbf n}$

$\newcommand{\pvec}{\mathbf p}$

$\newcommand{\qvec}{\mathbf q}$

$\newcommand{\svec}{\mathbf s}$

$\newcommand{\tvec}{\mathbf t}$

$\newcommand{\uvec}{\mathbf u}$

$\newcommand{\vvec}{\mathbf v}$

$\newcommand{\wvec}{\mathbf w}$

$\newcommand{\xvec}{\mathbf x}$

$\newcommand{\yvec}{\mathbf y}$

$\newcommand{\zvec}{\mathbf z}$

$\newcommand{\rvec}{\mathbf r}$

$\newcommand{\mvec}{\mathbf m}$

$\newcommand{\zerovec}{\mathbf 0}$

$\newcommand{\onevec}{\mathbf 1}$

$\newcommand{\real}{\mathbb R}$

$\newcommand{\twovec}[2]{\left[\begin{array}{r}#1 \\ #2 \end{array}\right]}$

$\newcommand{\ctwovec}[2]{\left[\begin{array}{c}#1 \\ #2 \end{array}\right]}$

$\newcommand{\threevec}[3]{\left[\begin{array}{r}#1 \\ #2 \\ #3 \end{array}\right]}$

$\newcommand{\cthreevec}[3]{\left[\begin{array}{c}#1 \\ #2 \\ #3 \end{array}\right]}$

$\newcommand{\fourvec}[4]{\left[\begin{array}{r}#1 \\ #2 \\ #3 \\ #4 \end{array}\right]}$

$\newcommand{\cfourvec}[4]{\left[\begin{array}{c}#1 \\ #2 \\ #3 \\ #4 \end{array}\right]}$

$\newcommand{\fivevec}[5]{\left[\begin{array}{r}#1 \\ #2 \\ #3 \\ #4 \\ #5 \\ \end{array}\right]}$

$\newcommand{\cfivevec}[5]{\left[\begin{array}{c}#1 \\ #2 \\ #3 \\ #4 \\ #5 \\ \end{array}\right]}$

$\newcommand{\mattwo}[4]{\left[\begin{array}{rr}#1 \amp #2 \\ #3 \amp #4 \\ \end{array}\right]}$

$\newcommand{\laspan}[1]{\text{Span}\{#1\}}$

$\newcommand{\bcal}{\cal B}$

$\newcommand{\ccal}{\cal C}$

$\newcommand{\scal}{\cal S}$

$\newcommand{\wcal}{\cal W}$

$\newcommand{\ecal}{\cal E}$

$\newcommand{\coords}[2]{\left\{#1\right\}_{#2}}$

$\newcommand{\gray}[1]{\color{gray}{#1}}$

$\newcommand{\lgray}[1]{\color{lightgray}{#1}}$

$\newcommand{\rank}{\operatorname{rank}}$

$\newcommand{\row}{\text{Row}}$

$\newcommand{\col}{\text{Col}}$

$\renewcommand{\row}{\text{Row}}$

$\newcommand{\nul}{\text{Nul}}$

$\newcommand{\var}{\text{Var}}$

$\newcommand{\corr}{\text{corr}}$

$\newcommand{\len}[1]{\left|#1\right|}$

$\newcommand{\bbar}{\overline{\bvec}}$

$\newcommand{\bhat}{\widehat{\bvec}}$

$\newcommand{\bperp}{\bvec^\perp}$

$\newcommand{\xhat}{\widehat{\xvec}}$

$\newcommand{\vhat}{\widehat{\vvec}}$

$\newcommand{\uhat}{\widehat{\uvec}}$

$\newcommand{\what}{\widehat{\wvec}}$

$\newcommand{\Sighat}{\widehat{\Sigma}}$

$\newcommand{\lt}{<}$

$\newcommand{\gt}{>}$

$\newcommand{\amp}{&}$

$\definecolor{fillinmathshade}{gray}{0.9}$

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

Access multimedia content

Concepts in Practice: HTML color codes

What color is #000080?

maroon red

navy blue

olive green

What is 255 in hexadecimal?

Which color is lighter?

#FFA500 (orange)
#008000 (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: The colors module

What are the components of the color YELLOW?

red=0, green=255, blue=255

red=255, green=255, blue=0

red=255, green=0, blue=255

What code would return a darker shade of blue?

darken(BLUE)
colors.darken(BLUE)
colors.darken(colors.BLUE)

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

underscore (_)
number sign (#)
colon (:)

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: The help() function

The documentation includes comments from the source code.

true

false

In what order are the functions listed in the documentation?

alphabetical order
definition order
random order

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

_tohex
tohex
torgb

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.