Grade by Grade
C. Computer Environments and Systems · Computer Environments and Systems

Working Independently with Documentation and Help

C3.2About 65 minutes
Learning goals
  • I can use built-in help, the official Python documentation, tutorials and my IDE's help to find out how something works.
  • I can read a function's documentation: its name, parameters, return value and edge cases.
  • I can read a traceback to locate and understand an error, and search for help effectively.
  • I can judge whether a help source is reliable and use it honestly, then design and write a working program on my own.

Words to know

documentation
Written information that explains how to use a language, library, tool or program.
library reference
The part of the official Python documentation that describes every built-in function and standard module.
docstring
A string written as the first line inside a function (or module) that documents it. help() displays it.
signature
A function's name and parameters, such as round(number, ndigits=None).
traceback
Python's error report: the chain of calls that led to the error, ending with the error type and message.
edge case
An unusual input at the limits of what a function handles, such as an empty list, zero or a tie.
academic integrity
Doing your own work and giving credit for help and code you used.

Nobody memorizes everything

Professional programmers look things up all day long. The Python standard library has hundreds of modules and thousands of functions; nobody remembers them all. What makes someone a strong programmer is knowing where to look and how to read what they find.

The curriculum asks you to work independently, using support documentation (IDE help, tutorials, websites, manuals) to design and write programs that work. This lesson builds that skill.

Where to find help, in order

  1. Built-in help, right in Python. At the >>> prompt in your shell, type help(round) or help(str.split) to read the documentation for a function. dir(str) lists everything a string can do. Press q to leave a long help page if one appears.
  2. Your IDE's help. The Help menu, hover tooltips (point at a function name to see its signature) and auto-completion lists.
  3. The official documentation at docs.python.org: the Tutorial (for learning), the Library Reference (every built-in function and module) and the Language Reference. Make sure the version selector matches your Python 3 version.
  4. Tutorials, courses and textbooks from reliable publishers.
  5. Question-and-answer sites and forums. Useful, but check the date, the Python version, and whether the answer was tested.
  6. AI assistants. They can explain ideas, but they can be confidently wrong. Test everything, never paste in code you do not understand, and follow your teacher's rules about when they are allowed.

Whatever you use, give credit: a comment such as # Based on the example in the Python docs for str.split is honest and helps anyone reading your code later.

Reading a documentation entry

Every function entry has the same parts: the module it belongs to, its name, its parameters (inputs; some have default values written as name=value) and a description of what it returns, including edge cases. Read the edge cases carefully; that is where surprises hide.

random.randint(a, b)Return a random integer N such that a <= N <= b.Alias for randrange(a, b+1).modulefunction nameparameters (inputs)the details: what it returns, and the edge cases(here: BOTH a and b can be chosen)From the Python LibraryReference (docs.python.org).
The parts of a documentation entry. The detail "a <= N <= b" tells you randint(1, 6) can return 6, unlike range(1, 6), which stops at 5.
print(round(2.5), round(3.5), round(2.675, 2))

A surprise? Most people expect 3 4 2.68. The documentation for round explains both: halfway values are rounded to the even choice, and 2.675 cannot be stored exactly as a binary fraction, so it is really slightly less than 2.675. Output: 2 4 2.67

Reading error messages: the traceback

When a Python program crashes, it prints a traceback. Read it from the bottom up:

  1. The last line gives the error type and a message: ZeroDivisionError: division by zero.
  2. Just above it is the file, line number and function where it broke, and the line of code itself.
  3. Higher lines show the chain of calls that led there, starting from your main code.

Then: go to that line, think about what the values must have been, and if you still need help, search for the error type and message, leaving out your own variable names, which nobody else uses.

Traceback (most recent call last):File "avg.py", line 4, in <module>print(average([]))File "avg.py", line 2, in averagereturn sum(marks) / len(marks)ZeroDivisionError: division by zero1. where it started (your main code)2. where it actually broke: file, line number, function, and the line itself3. READ THIS FIRST: error type + messageRead a traceback from the bottom up. (Newer Pythons also add ~ and ^ marks under the exact spot.)
The traceback for average([]): an empty list has length 0, and dividing by zero is not allowed. The bottom line tells you what went wrong; the line above it tells you where.
Worked example

Example 1: Learn a function from its documentation

You need to turn the line Ava,92,88 into a name and two marks. You have never used str.split. Use the documentation to write the program.

  1. In the shell, type help(str.split). The signature is split(self, /, sep=None, maxsplit=-1), and the description says it returns a list of the substrings, using sep as the separator. (Ignore self and / for now.)
  2. Test a tiny case first, at the prompt: "Ava,92,88".split(",") gives ['Ava', '92', '88'].
  3. The pieces are strings, so use int() to turn the marks into numbers before doing arithmetic.
  4. Write the program and test it.

The program below works, and the comment gives credit to the source.

# split() learned from help(str.split) and the Python docs
line = "Ava,92,88"
parts = line.split(",")
name = parts[0]
average = (int(parts[1]) + int(parts[2])) / 2
print(name, "has an average of", average)

Output: Ava has an average of 90.0

Worked example

Example 2: Use a traceback to fix a program

A program prints this. Find and fix the problem.

  1. Traceback (most recent call last):
  2.   File "tickets.py", line 3, in <module>
  3.     total = price * qty
  4. TypeError: can't multiply sequence by non-int of type 'float'
  1. Bottom line first: a TypeError. Python tried to multiply a sequence (a string is a sequence of characters) by a float.
  2. Line 3: total = price * qty. So one of these is a string. Most likely qty came from input(), which always returns a string, while price is a float such as 12.5.
  3. Check the documentation for input: it says it returns the line typed as a string. So convert it: qty = int(input("How many tickets? ")).
  4. Run again with input 3: total = 12.5 * 3 = 37.5.

qty was a string from input(). Converting it with int() fixes the TypeError.

Just for fun

Some programmers keep a rubber duck on their desk and explain their code to it, line by line. Surprisingly often, they find the bug halfway through the explanation. It is called rubber duck debugging, and the duck never interrupts.

Hands-on activity

Documentation scavenger hunt

You need: a computer with Python. Use only help(), dir(), your IDE's help and docs.python.org (no asking anyone, and no AI assistant for this activity).

  1. Find out what each of these does, write one sentence for each, and test it at the >>> prompt: str.title, str.strip, str.join, str.count, math.isqrt, math.hypot.
  2. Find the edge case: what does "a,b,,c".split(",") return, and why is there an empty string in it?
  3. Find which function in the math module rounds up to a whole number. Test it on 4.1.
  4. Design and write a small program on your own using at least three of these functions: for example, a program that takes a list of names typed with extra spaces and odd capitals and prints them neatly as "Maple, Pine, Spruce". Credit your sources in comments.
  5. Add a docstring to one function in your program and print it with print(your_function.__doc__).

What to look for: correct sentences (for example, str.count counts non-overlapping occurrences of a substring), the answer ['a', 'b', '', 'c'] (the empty string is the "nothing" between the two commas), math.ceil(4.1) gives 5, and a working, commented program.

Your turn

1

How do you read the built-in documentation for len at the Python prompt?

2

What does print(round(4.5)) output, and why?

3

Can random.randint(1, 10) return 10? How do you know?

4

In a traceback, which line should you read first?

5

Give two things to check before trusting an answer on a forum.

6

What does "ics3u".upper().center(11, "*") produce? Use help(str.center) if needed.

7

Why should you credit sources in your code comments?

More practice: warm-up

1

What is the website for the official Python documentation?

2

What does dir(str) show?

3

What is a docstring?

4

What does "banana".count("an") return?

5

What type of value does input() always return?

More practice: on your own

1

Using the documentation for str.find, predict "banana".find("n") and "banana".find("z").

2

A traceback ends with IndexError: list index out of range on the line print(names[5]). What does it mean, and what would you check?

3

Explain why searching for TypeError: can't multiply sequence by non-int of type 'float' works better than searching "my ticket program broken".

4

math.sqrt(16) and math.isqrt(17): predict both outputs using the docs.

5

Write a function area(w, h) with a docstring, and show what print(area.__doc__) prints.

Challenge

1

Use the documentation for math.hypot to write one line that prints the length of the hypotenuse of a right triangle with legs 3 and 4. Then explain how you would check it without a computer.

2

An AI assistant tells you that list.add(x) adds an item to a Python list. How would you check this, and what is the truth?

3

A forum answer says to write print "Hello". Why does this fail in your Python, and what does that teach about using sources?

Check your understanding

Quiz

1.

Which is the best first place to check how a built-in Python function works?

2.

What does print(round(2.5)) output in Python 3?

3.

A traceback's last line is NameError: name 'totl' is not defined. What is the most likely cause?

4.

According to its documentation, random.randint(1, 6) can return...

5.

A forum answer from many years ago uses print "Hi". What should you conclude?

6.

Why credit help you used in comments?

For parents and teachers

Big idea: Expectation C3.2 asks students to work independently, using support documentation (IDE help, tutorials, websites, manuals) to design and write functioning programs. Independence is the goal: the skill of looking things up, not memorizing.

How to help: When your teen asks you how to do something in Python, try asking "What did help() or the documentation say?" first. Sit with them while they read a traceback aloud from the bottom up. Talk about the school's rules for using AI tools and online code.

Common difficulties:

  • Reading tracebacks from the top and getting lost; the bottom line matters most.
  • Copying code from forums or AI without understanding or testing it.
  • Using answers written for Python 2.
  • Skipping the edge cases in documentation (inclusive ends, empty inputs, rounding).