Using Help

Using Help

Python is a computer language, not a human language. As a result, you won’t speak it fluently at first. If you think about it for a moment, it makes sense that you won’t speak Python fluently (and as with most human languages, you won’t know every command even after you do become fluent). Having  to discover Python commands a little at a time is the same thing that hap- pens when you learn to speak another human language. If you normally speak English and try to say something in German, you find that you must have some sort of guide to help you along. Otherwise, anything you say is gibberish and people will look at you quite oddly. Even if you manage to say something that makes sense, it may not be what you want. You might go to

a restaurant and order hot hubcaps for dinner when what you really wanted was a steak.

Likewise, when you try to speak Python, you need a guide to help you. Fortu- nately, Python is quite accommodating and provides immediate help to keep you from ordering something you really don’t want. The help provided inside Python works at two levels:

• Help mode, in which you can browse the available commands
• Direct help, in which you ask about a specific command

There isn’t a correct way to use help — just the method that works best for you at a particular time. The following sections describe how to obtain help.

Getting into help mode

When you first start Python, you see a display similar to the one shown in Figure 3-1. Notice that Python provides you with four commands at the outset (which is actually your first piece of help information):

• help
• copyright
• credits
• license

All four commands provide you with help, of a sort, about Python. For exam- ple, the copyright() command tells you about who holds the right to copy, license, or otherwise distribute Python. The credits() command tells you

who put Python together. The license() command describes the usage agreement between you and the copyright holder. However, the command you most want to know about is simply help().

To enter help mode, type help( ) and press Enter. Notice that you must include the parentheses after the command even though they don’t appear in the help text. Every Python command has parentheses associated with it.

After you enter this command, Python goes into help mode and you see a dis- play similar to the one shown in Figure 3-3.

Figure 3-3: You ask Python about other commands

in help mode.

You can always tell that you’re in help mode by the help> prompt that you see in the Python window. As long as you see the help> prompt, you know that you’re in help mode.

Asking for help

To obtain help, you need to know what question to ask. The initial help mes- sage that you see when you go into help mode (refer to Figure 3-3) provides some helpful tips about the kinds of questions you can ask. If you want to explore Python, the three basic topics are

• modules
• keywords
• topics

The first two topics won’t tell you much for now. You won’t need the modules topic until Chapter 10. The keywords topic will begin proving useful in Chapter 4. However, the topics keyword is already useful because it helps you understand where to begin your Python adventure. To see what topics  are available, type topics and press Enter. You see a list of topics similar to those shown in Figure 3-4.

Figure 3-4:

The topics help topic provides you with a starting point for

your Python adventure.

When you see a topic that you like, such as FUNCTIONS, simply type that topic and press Enter. To see how this works, type FUNCTIONS and press Enter (you must type the word in uppercase — don’t worry, Python won’t think you’re shouting). You see help information similar to that shown in Figure 3-5.

Figure 3-5:

You must

use uppercase

when requesting

topic information.

As you work through examples in the book, you use commands that look interesting, and you might want more information about them. For example, in the “Seeing the result” section of this chapter, you use the print() com- mand. To see more information about the print() command, type print and press Enter (notice that you don’t include the parentheses this time because you’re requesting help about print(), not actually using the command).

Figure 3-6 shows typical help information for the print() command.

Figure 3-6:

Request

com­ mand help information by typing the command

using whatever case it actually uses.

Unfortunately, reading the help information probably doesn’t help much yet because you need to know more about Python. However, you can ask for more information. For example, you might wonder what sys.stdout means — and the help topic certainly doesn’t tell you anything about it. Type sys.stdout and press Enter. You see the help information shown in Figure 3-7.

Figure 3-7: You can ask for help on the help you

receive.

You may still not find the information as helpful as you need, but at least you know a little more. In this case, help has a lot to say and it can’t all fit on one screen. Notice the following entry at the bottom of the screen:

To see the additional information, press the spacebar. The next page of help appears. As you read to the bottom of each page of help, you can press the spacebar to see the next page. The pages don’t go away — you can scroll up to see previous material.

Leaving help mode

At some point, you need to leave help mode to perform useful work. All you have to do is press Enter without typing anything. When you press Enter, you see a message about leaving help, and then the prompt changes to the stan- dard Python prompt, as shown in Figure 3-8.

Figure 3-8: Exit help mode by pressing Enter with­ out typing anything.

Obtaining help directly

Entering help mode isn’t necessary unless you want to browse, which is always a good idea, or unless you don’t actually know what you need to find. If you have a good idea of what you need, all you need to do is ask for help directly (a really nice thing for Python to do). So, instead of fiddling with  help mode, you simply type the word help, followed by a left parenthesis and

single quote, whatever you want to find, another single quote, and the right parenthesis. For example, if you want to know more about the print() com- mand, you type help(‘print’) and press Enter. Figure 3-9 shows typical output when you access help this way.

Figure 3-9:

Python makes it possible to obtain help whenever you need

it without leaving the Python prompt.

You can browse at the Python prompt, too. For example, when you type help(‘topics’) and press Enter, you see a list of topics like the one that appears in Figure 3-10. You can compare this list with the one shown in Figure 3-4. The two lists are identical, even though you typed one while in help mode and the other while at the Python prompt.

Figure 3-10: It’s possible to browse at the Python prompt if you really want to.

You might wonder why Python has a help mode at all if you can get the same results at the Python prompt. The answer is convenience. It’s easier to browse in the help mode. In addition, even though you don’t do a lot of extra typing

at the prompt, you do perform less typing while in help mode. Help mode also provides additional helps, such as by listing commands that you can type, as shown in Figure 3-3. So you have all kinds of good reasons to enter help mode when you plan to ask Python a lot of help questions.

No matter where you ask for help, you need to observe the correct capitaliza- tion of help topics. For example, if you want general information about func- tions, you must type help(‘FUNCTIONS’) and not help(‘Functions’) or help(‘functions’). When you use the wrong capitalization, Python will tell you that it doesn’t know what you mean or that it couldn’t find the help topic. It won’t know to tell you that you used the wrong capitalization. Someday computers will know what you meant to type, rather than what you did type, but  that  hasn’t  happened  yet.